binlore - generate and aggregate info about executables in nix packages

Since binlore is very young and currently has a limited scope, the vision may make a little more sense if I outline what it currently does and why. If you'd like to help improve binlore, see How to help

Why / Motive

I'm building binlore to help resholve decide how likely the executables it finds in shell scripts are to also execute one of their arguments.

This information helps resholve scrutinize these invocations more carefully and require user triage as-needed (without wasting user time on unlikely cases).

What / API (high level)

binlore itself is a Nix API with two main functions:

make which builds a derivation that runs a black-box we'll call [analysis] for a single package and outputs a directory with one or more named files containing some or all of the output from that analysis.
collect which builds a derivation that depends on and aggregates the output of make for each package in a list. In this case, aggregation means concatenating files with the same name for every package into a single file of the same name.
It'll take some use for norms/patterns to settle, but I tentatively see each file as a "type" or "kind" of lore.

Trying out the API

If you want to contribute to binlore or use binlore in your own project, then you’ll probably want to see what lore binlore produces for particular commands. Here’s how you would get the lore for hello and haskellPackages.hello:

$ git clone https://github.com/abathur/binlore.git
$ cd binlore
$ nix-build -E 'with import <nixpkgs> { }; (callPackage ./binlore.nix { binloreSrc = ./.; }).collect { drvs = [ hello haskellPackages.hello ]; }'
/nix/store/...-more-binlore
$ cat result/execers
cannot:/nix/store/...-hello-2.12.1/bin/hello
cannot:/nix/store/...-hello-1.0.0.2/bin/hello
$ cat result/wrappers
$

In this example, result/wrappers is empty.

How / Analyses

The only [analysis] so far meets resholve's immediate needs. You can find its definition in the loreDev attr in default.nix, but the broad strokes are that it:

runs YARA with a single YARA ruleset on ${package}/bin
defines two "kinds" of lore (see Lore Formats for detail): execers, and wrappers
pipes the output through yallback (which supports shell callbacks for rule matches) using a single callback script to extract these two lore types

Trying out the analyses (low-level)

Sometimes it's enough to see the high-level lore produced by the collect function for a specific package or executable, and other times you'll need to pop open the hood to understand how binlore's YARA rules are leading to a specific result. (Perhaps because it's wrong, or perhaps because binlore just doesn't have rules for a specific language or binary format.)

With the traditional nix commands, you can do something like:

$ git clone https://github.com/abathur/binlore.git
$ cd binlore
$ nix-shell
$ binlore_yara /nix/store/...-diffutils-3.10
...
executable /nix/store/...-diffutils-3.10/bin/cmp
macho_binary /nix/store/...-diffutils-3.10/bin/cmp
binary /nix/store/...-diffutils-3.10/bin/cmp
macho_cannot_exec /nix/store/...-diffutils-3.10/bin/cmp
decidable /nix/store/...-diffutils-3.10/bin/cmp
cannot_exec /nix/store/...-diffutils-3.10/bin/cmp
executable /nix/store/...-diffutils-3.10/bin/diff
macho_binary /nix/store/...-diffutils-3.10/bin/diff
binary /nix/store/...-diffutils-3.10/bin/diff
macho_execve /nix/store/...-diffutils-3.10/bin/diff
execve /nix/store/...-diffutils-3.10/bin/diff
decidable /nix/store/...-diffutils-3.10/bin/diff
can_exec /nix/store/...-diffutils-3.10/bin/diff

Using the experimental CLI you can do something like:

$ nix develop github.com:abathur/binlore
$ binlore_yara /nix/store/...-diffutils-3.10
...
executable /nix/store/...-diffutils-3.10/bin/cmp
macho_binary /nix/store/...-diffutils-3.10/bin/cmp
binary /nix/store/...-diffutils-3.10/bin/cmp
macho_cannot_exec /nix/store/...-diffutils-3.10/bin/cmp
decidable /nix/store/...-diffutils-3.10/bin/cmp
cannot_exec /nix/store/...-diffutils-3.10/bin/cmp
executable /nix/store/...-diffutils-3.10/bin/diff
macho_binary /nix/store/...-diffutils-3.10/bin/diff
binary /nix/store/...-diffutils-3.10/bin/diff
macho_execve /nix/store/...-diffutils-3.10/bin/diff
execve /nix/store/...-diffutils-3.10/bin/diff
decidable /nix/store/...-diffutils-3.10/bin/diff
can_exec /nix/store/...-diffutils-3.10/bin/diff

Each line here indicates that a YARA rule of the same name (currently in execers.yar) matched for that path.

Note: You may also want to fork this repo, add the relevant package to big.nix (if it isn't already there), and push it up to github to run the CI process. The CI job will dump this information (and some additional analysis) for all included packages.

Lore Formats

There are currently two "kinds" of lore. In both cases below, the field separator is equivalent to FIELD_SEPARATOR=$':':

$out/execers, which has the format: ${verdict}${FIELD_SEPARATOR}${executable_path} where:
- verdict=can|cannot|might
- executable_path is whatever path YARA printed for the match
$out/wrappers, which has the format ${wrapper_path}${FIELD_SEPARATOR}${wrapped_path} where:
- wrapper_path is a path identified as a wrapper by YARA
- wrapped_path is the path that the shell_wrapper yallback and exec_target function in execers.yall pick out of the source of the wrapper

Usage / Examples

For now, at least, resholve's own uses of binlore should serve as a good example of the rough intent and usage:

direct use for CI run: https://github.com/abathur/resholve/commit/52faf7493c51e5191de771eb49b8c12df90357cd#diff-783b1f6267f9b548283102092f66f71ac066b9e7b0917de0663e0269e1e26848R168
similar use inside resholve's Nix API: https://github.com/abathur/resholve/commit/52faf7493c51e5191de771eb49b8c12df90357cd#diff-4ac4c92c1fad1b94f9defdc9f1c25bae0b446daa168078ce6e453ae7077a1908R80

abathur / binlore