capagap 0.1.0__tar.gz

capagap-0.1.0/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json}]
+indent_size = 2

capagap-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

capagap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: windows-latest
+            python-version: "3.14"
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python scripts/release_check.py

capagap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: github.repository == 'sawyershoemaker/capagap' && !github.event.release.prerelease
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.14"
+      - run: python -m pip install -e ".[dev]"
+      - name: Check and build the release
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python scripts/release_check.py --tag "$RELEASE_TAG" --outdir dist
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/capagap/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

capagap-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+.env
+.env.*
+.DS_Store
+Thumbs.db
+/cases/
+/samples/
+/reports/
+*.idb
+*.i64
+*.bndb
+*.gpr
+*.rep/

capagap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sawyer Shoemaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capagap-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include .editorconfig
+include .gitattributes
+include .gitignore
+recursive-include .github *.yml
+recursive-include docs *.md
+recursive-include examples *.html *.json *.md *.py *.txt *.yml
+recursive-include scripts *.py
+recursive-include tests *.py
+recursive-include src/capagap/importers *.tmpl
+recursive-include src/capagap/assets *.css *.js

capagap-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: capagap
+Version: 0.1.0
+Summary: Measure malware capability coverage across static analysis and labeled sandbox runs.
+Author: Sawyer Shoemaker
+License-Expression: MIT
+Project-URL: Repository, https://github.com/sawyershoemaker/capagap
+Project-URL: Issues, https://github.com/sawyershoemaker/capagap/issues
+Project-URL: Documentation, https://github.com/sawyershoemaker/capagap/blob/main/docs/CLI.md
+Keywords: malware-analysis,reverse-engineering,capa,sandbox,dfir
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Dynamic: license-file
+
+# CapaGap
+
+Compare static [capa](https://github.com/mandiant/capa) matches with dynamic runs of the same sample. CapaGap reports which capabilities were observed, which were missing, and which appeared in only some runs.
+
+Rules without a supported dynamic scope are excluded from coverage. Results include ranked findings, static match locations, and optional Ghidra, IDA Pro, and Binary Ninja annotations. CapaGap reads result documents; it does not run samples or contact a sandbox.
+
+## Install
+
+Python 3.10 or newer. No runtime dependencies.
+
+Install from PyPI:
+
+```sh
+python -m pip install capagap
+capagap --help
+```
+
+Or install from a source checkout:
+
+```sh
+python -m pip install .
+```
+
+If your shell cannot find `capagap`, use `python -m capagap` instead.
+
+## Try it
+
+The examples below use files from the [source repository](https://github.com/sawyershoemaker/capagap). Download the source and run these commands from its root directory; `pip install` does not copy the examples into your working directory.
+
+The inputs are synthetic. You do not need capa or a malware sample to run them.
+
+```sh
+capagap compare examples/static.json examples/dynamic.json
+```
+
+Excerpt from the result:
+
+```text
+Confidence:  high
+Coverage:    50.0% (2/4 comparable static capabilities observed)
+Unobserved:  2
+Static-only: 1 (excluded from coverage)
+```
+
+For your own inputs, export the static and dynamic results with `capa -j`. Use the same sample and ruleset for both analyses. Plain JSON and gzip-compressed JSON are accepted.
+
+### Compare runs
+
+```sh
+capagap matrix examples/static.json \
+  --run baseline=examples/dynamic.json \
+  --run interactive=examples/dynamic-interactive.json \
+  --condition baseline:interaction=off \
+  --condition interactive:interaction=on \
+  --format html --output reports/matrix.html
+```
+
+The first run is the baseline. Conditions are supplied by the analyst, not inferred from the reports. CapaGap warns when a comparison changes zero or multiple declared conditions.
+
+The example has 75% combined coverage: three of four comparable static capabilities appeared in at least one run. Open `reports/matrix.html` locally to compare runs, expand evidence, and copy addresses. Search covers rule names, namespaces, ATT&CK IDs, and locations. Runtime-only and excluded matches have separate views.
+
+HTML reports are self-contained: no server, external assets, or network requests. They include JSON export and remain readable with JavaScript disabled. Text, Markdown, and JSON output are also available.
+
+Multiline examples use POSIX shell continuations. In PowerShell, put the command on one line or replace each trailing `\` with a backtick.
+
+### Check the ruleset
+
+```sh
+capagap manifest path/to/capa-rules --output reports/ruleset.json
+capagap compare static.json dynamic.json --ruleset-manifest reports/ruleset.json
+```
+
+Build the manifest from the rule directory used for analysis. Comparable static rules with missing or different source definitions are reported as `ruleset-unverified` and removed from the coverage denominator. A dynamic match that disagrees with the manifest stops the comparison.
+
+### Export annotations
+
+```sh
+capagap handoff examples/static.json \
+  --run baseline=examples/dynamic.json \
+  --output reports/handoff
+```
+
+The output directory contains the findings, an editable triage worksheet, import scripts, and tool-specific instructions. Static match locations are exported as RVAs and rebased against the open database.
+
+After editing `reports/handoff/capagap-triage.json`, create a reviewed copy:
+
+```sh
+capagap triage apply reports/handoff/capagap-handoff.json \
+  reports/handoff/capagap-triage.json \
+  --output reports/handoff/reviewed.json
+```
+
+Re-importing updates the corresponding CapaGap annotations. See the [command reference](https://github.com/sawyershoemaker/capagap/blob/main/docs/CLI.md) for selection options, review fields, and exit codes.
+
+## Limits
+
+- A missing dynamic match is not proof that code did not execute. Trace loss, absent stimuli, packing, and extractor differences can all affect coverage.
+- A ruleset manifest checks source consistency. It cannot prove that every listed rule was loaded during a historical run.
+- Scores set an investigation order; they are not probabilities or severity ratings. Evidence hotspots group exact RVAs, not functions or call-graph edges.
+- Absolute addresses require the static report's image base for handoff. Other address types remain in the bundle as unmappable evidence.
+
+Analysis reports can contain sensitive paths and strings. There is no automatic redaction; review them before sharing.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python scripts/release_check.py
+```
+
+The release check runs lint, formatting checks, tests, package builds, metadata validation, and a clean-environment install test. It does not publish anything. The output directory must be empty; use `--outdir path/to/empty-directory` to keep an existing build.
+
+The version is defined in `src/capagap/__init__.py`. Release tags use `v` followed by that version.
+
+More detail: [command reference](https://github.com/sawyershoemaker/capagap/blob/main/docs/CLI.md), [comparison model](https://github.com/sawyershoemaker/capagap/blob/main/docs/DESIGN.md), [experiment setup](https://github.com/sawyershoemaker/capagap/blob/main/docs/EXPERIMENTS.md), and [example data](https://github.com/sawyershoemaker/capagap/blob/main/examples/README.md).
+
+## License
+
+[MIT](https://github.com/sawyershoemaker/capagap/blob/main/LICENSE). Copyright 2026 Sawyer Shoemaker.

capagap-0.1.0/README.md

@@ -0,0 +1,120 @@
+# CapaGap
+
+Compare static [capa](https://github.com/mandiant/capa) matches with dynamic runs of the same sample. CapaGap reports which capabilities were observed, which were missing, and which appeared in only some runs.
+
+Rules without a supported dynamic scope are excluded from coverage. Results include ranked findings, static match locations, and optional Ghidra, IDA Pro, and Binary Ninja annotations. CapaGap reads result documents; it does not run samples or contact a sandbox.
+
+## Install
+
+Python 3.10 or newer. No runtime dependencies.
+
+Install from PyPI:
+
+```sh
+python -m pip install capagap
+capagap --help
+```
+
+Or install from a source checkout:
+
+```sh
+python -m pip install .
+```
+
+If your shell cannot find `capagap`, use `python -m capagap` instead.
+
+## Try it
+
+The examples below use files from the [source repository](https://github.com/sawyershoemaker/capagap). Download the source and run these commands from its root directory; `pip install` does not copy the examples into your working directory.
+
+The inputs are synthetic. You do not need capa or a malware sample to run them.
+
+```sh
+capagap compare examples/static.json examples/dynamic.json
+```
+
+Excerpt from the result:
+
+```text
+Confidence:  high
+Coverage:    50.0% (2/4 comparable static capabilities observed)
+Unobserved:  2
+Static-only: 1 (excluded from coverage)
+```
+
+For your own inputs, export the static and dynamic results with `capa -j`. Use the same sample and ruleset for both analyses. Plain JSON and gzip-compressed JSON are accepted.
+
+### Compare runs
+
+```sh
+capagap matrix examples/static.json \
+  --run baseline=examples/dynamic.json \
+  --run interactive=examples/dynamic-interactive.json \
+  --condition baseline:interaction=off \
+  --condition interactive:interaction=on \
+  --format html --output reports/matrix.html
+```
+
+The first run is the baseline. Conditions are supplied by the analyst, not inferred from the reports. CapaGap warns when a comparison changes zero or multiple declared conditions.
+
+The example has 75% combined coverage: three of four comparable static capabilities appeared in at least one run. Open `reports/matrix.html` locally to compare runs, expand evidence, and copy addresses. Search covers rule names, namespaces, ATT&CK IDs, and locations. Runtime-only and excluded matches have separate views.
+
+HTML reports are self-contained: no server, external assets, or network requests. They include JSON export and remain readable with JavaScript disabled. Text, Markdown, and JSON output are also available.
+
+Multiline examples use POSIX shell continuations. In PowerShell, put the command on one line or replace each trailing `\` with a backtick.
+
+### Check the ruleset
+
+```sh
+capagap manifest path/to/capa-rules --output reports/ruleset.json
+capagap compare static.json dynamic.json --ruleset-manifest reports/ruleset.json
+```
+
+Build the manifest from the rule directory used for analysis. Comparable static rules with missing or different source definitions are reported as `ruleset-unverified` and removed from the coverage denominator. A dynamic match that disagrees with the manifest stops the comparison.
+
+### Export annotations
+
+```sh
+capagap handoff examples/static.json \
+  --run baseline=examples/dynamic.json \
+  --output reports/handoff
+```
+
+The output directory contains the findings, an editable triage worksheet, import scripts, and tool-specific instructions. Static match locations are exported as RVAs and rebased against the open database.
+
+After editing `reports/handoff/capagap-triage.json`, create a reviewed copy:
+
+```sh
+capagap triage apply reports/handoff/capagap-handoff.json \
+  reports/handoff/capagap-triage.json \
+  --output reports/handoff/reviewed.json
+```
+
+Re-importing updates the corresponding CapaGap annotations. See the [command reference](https://github.com/sawyershoemaker/capagap/blob/main/docs/CLI.md) for selection options, review fields, and exit codes.
+
+## Limits
+
+- A missing dynamic match is not proof that code did not execute. Trace loss, absent stimuli, packing, and extractor differences can all affect coverage.
+- A ruleset manifest checks source consistency. It cannot prove that every listed rule was loaded during a historical run.
+- Scores set an investigation order; they are not probabilities or severity ratings. Evidence hotspots group exact RVAs, not functions or call-graph edges.
+- Absolute addresses require the static report's image base for handoff. Other address types remain in the bundle as unmappable evidence.
+
+Analysis reports can contain sensitive paths and strings. There is no automatic redaction; review them before sharing.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+python scripts/release_check.py
+```
+
+The release check runs lint, formatting checks, tests, package builds, metadata validation, and a clean-environment install test. It does not publish anything. The output directory must be empty; use `--outdir path/to/empty-directory` to keep an existing build.
+
+The version is defined in `src/capagap/__init__.py`. Release tags use `v` followed by that version.
+
+More detail: [command reference](https://github.com/sawyershoemaker/capagap/blob/main/docs/CLI.md), [comparison model](https://github.com/sawyershoemaker/capagap/blob/main/docs/DESIGN.md), [experiment setup](https://github.com/sawyershoemaker/capagap/blob/main/docs/EXPERIMENTS.md), and [example data](https://github.com/sawyershoemaker/capagap/blob/main/examples/README.md).
+
+## License
+
+[MIT](https://github.com/sawyershoemaker/capagap/blob/main/LICENSE). Copyright 2026 Sawyer Shoemaker.

capagap-0.1.0/docs/CLI.md

@@ -0,0 +1,135 @@
+# Command reference
+
+Run `capagap COMMAND --help` for the accepted options. Commands below assume the current directory is the project root. Output goes under `reports/`, which is ignored by git.
+
+## compare
+
+```sh
+capagap compare STATIC DYNAMIC [options]
+```
+
+Both inputs must be capa result documents. The first must have `meta.flavor` set to `static`, the second to `dynamic`. Gzip is detected by its file signature.
+
+| Option | Effect |
+|---|---|
+| `--format text\|markdown\|json\|html` | Choose a report format. Default: `text`. |
+| `--output PATH` | Write a report instead of printing it. An existing report is overwritten. |
+| `--minimum-priority low\|medium\|high\|critical` | Filter gap findings in text and Markdown output. Default: `low`. |
+| `--limit N` | Limit rows in human-readable sections. Default: `25`; minimum: `1`. |
+| `--include-library` | Include capa helper/library rules, which are excluded by default. |
+| `--allow-mismatch` | Permit different sample SHA-256 values and mark the comparison low-confidence. |
+| `--ruleset-manifest PATH` | Compare rule source digests against a manifest. |
+| `--fail-on-unobserved` | Return `3` if any comparable static capability is unobserved. |
+
+JSON and HTML reports retain all findings. Priority filters do not change summary counts or exit-code checks.
+
+## matrix
+
+```sh
+capagap matrix STATIC --run LABEL=PATH --run LABEL=PATH [options]
+```
+
+A matrix needs at least two dynamic results with unique, nonempty labels. It accepts the report options above, except that `--fail-on-never-observed` replaces `--fail-on-unobserved`.
+
+The report separates capabilities seen in all runs, seen in only some runs (`environment-sensitive`), and absent from every run (`never-observed`). Coverage is also calculated for the union of all supplied runs.
+
+Repeat `--condition LABEL:KEY=VALUE` to record run settings. The first run is the baseline. Each other run is checked for the number of changed keys; zero or multiple changes produce warnings. Unknown labels and duplicate keys within a run are errors. These are checks of declared metadata, not measurements of the sandbox configuration.
+
+See [experiment setup](EXPERIMENTS.md) for a worked example.
+
+## HTML reports
+
+Both comparison commands accept `--format html --output REPORT.html`. Open the file in a modern browser; no web server or internet connection is needed.
+
+The matrix starts with comparable capabilities. Use the Runtime-only and Excluded controls to inspect other findings without changing coverage. Expand a row to see its evidence, scopes, identifiers, and follow-up. Runtime-only evidence is labeled by run and retains its original address type. Static addresses show a portable RVA when one can be calculated; unmapped locations remain visible.
+
+Search is case-insensitive and matches every space-separated term within a finding's name, namespace, state, identifiers, or evidence locations. The state filter combines with search. Switching views clears the state filter but preserves search. Run conditions, exact-RVA hotspots, input metadata, and analysis context sit below the matrix. Input warnings are expanded by default.
+
+| Control | Keyboard behavior |
+|---|---|
+| Search | `/` focuses search when not typing in another control. |
+| Row disclosure | Enter or Space toggles evidence; Right opens it; Left closes it. |
+| Row navigation | Up and Down move between visible row disclosure buttons. |
+| Evidence | Escape closes the row and returns focus to its disclosure button. |
+| Copy dialog | If automatic copying is blocked, select the text and copy manually. Escape closes the dialog. |
+
+Export JSON downloads the complete report, not just the filtered view. Copy controls are available for evidence addresses, mapped RVAs, image bases, and sample hashes. Printing includes all findings and evidence, including filtered-out rows. With JavaScript disabled, all rows and evidence remain visible; filtering, copying, and export controls are unavailable.
+
+The HTML file embeds the report data. Paths and strings are not redacted; check them before sharing the file or its JSON export.
+
+## manifest
+
+```sh
+capagap manifest RULE_DIRECTORY --output reports/ruleset.json
+```
+
+Scans `.yml` and `.yaml` files recursively. The manifest stores names, scopes, library flags, relative paths, and SHA-256 digests of rule source text with CRLF normalized to LF. Rule names must be unique. Unrelated YAML files are listed as skipped.
+
+The metadata reader supports the indented capa rule format, not arbitrary YAML. It does not execute tags or resolve anchors. This command is not a replacement for capa's rule validation.
+
+Supply the resulting file with `--ruleset-manifest` on `compare`, `matrix`, or `handoff`. Matched dynamic rules must agree with the manifest. Comparable static rules without an exact source match are excluded from coverage and listed separately as `ruleset-unverified`.
+
+Existing manifests require `--force` to overwrite. A supplied manifest is a consistency check, not evidence of which rules were loaded in an earlier analysis.
+
+## handoff
+
+```sh
+capagap handoff STATIC --run LABEL=PATH --output DIRECTORY [options]
+```
+
+One run exports unobserved findings. Two or more runs export never-observed and environment-sensitive findings. Multi-run handoffs accept the same `--condition` syntax as `matrix`.
+
+| Option | Effect |
+|---|---|
+| `--tool all\|json\|ghidra\|ida\|binary-ninja` | Choose import scripts. Default: `all`. |
+| `--minimum-priority low\|medium\|high\|critical` | Select findings by score. Default: `low`. |
+| `--never-only` | Exclude environment-sensitive findings. Requires at least two runs. |
+| `--ruleset-manifest PATH` | Verify rule sources before exporting findings. |
+| `--include-library` | Include helper/library rules in the analysis. |
+| `--allow-mismatch` | Permit mismatched report hashes. Importers still reject a known database hash mismatch. |
+| `--force` | Overwrite existing output files, including the triage worksheet. |
+
+The output includes:
+
+| File | Purpose |
+|---|---|
+| `capagap-handoff.json` | Selected findings, evidence locations, and comments. |
+| `capagap-triage.json` | Editable analyst reviews. |
+| `README.txt` | Import instructions. |
+| `CapaGapImport_Ghidra.py` | Ghidra Analysis bookmarks in the CapaGap category. |
+| `capagap_import_ida.py` | IDA repeatable comments. |
+| `capagap_import_binja.py` | Binary Ninja address comments. |
+
+Script selection does not affect the JSON bundle. `--tool json` writes only the two JSON files and instructions.
+
+Absolute match addresses are converted to RVAs using `meta.analysis.base_address`. Export fails if that base is missing and the selection contains absolute evidence. File offsets, .NET tokens, and dynamic coordinates are retained as unmappable evidence rather than converted to virtual addresses. Importers skip unmapped addresses and reject a known sample-hash mismatch.
+
+## triage
+
+Handoff generation creates a worksheet automatically. For an existing bundle:
+
+```sh
+capagap triage init HANDOFF --output WORKSHEET
+capagap triage report HANDOFF WORKSHEET --format markdown --output reports/review.md
+capagap triage apply HANDOFF WORKSHEET --output reports/reviewed-handoff.json
+```
+
+Each review contains a stable finding ID, disposition, analyst notes, evidence, reviewer, and review date. The text fields are free-form. Do not change the finding ID or `handoff_identity` field.
+
+Accepted dispositions: `unreviewed`, `confirmed`, `likely`, `benign`, `false-positive`, `needs-data`, and `deferred`. CapaGap records these as analyst judgments; it does not verify them.
+
+The worksheet identity is a hash of the sample SHA-256 and sorted finding IDs. A mismatch stops `report` or `apply`. This is an accidental-mixup check, not a signature or a complete record of run provenance.
+
+`init` and `apply` require `--force` to replace an existing output. `report` accepts `text` or `markdown` and overwrites its output path if one is supplied. Applying a worksheet writes a new handoff; it does not modify the original unless explicitly given the same path with `--force`.
+
+IDA and Binary Ninja imports replace comment lines with matching CapaGap markers. Ghidra updates the CapaGap bookmark at each location. Keep a database backup before importing annotations.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Command completed. |
+| `2` | Invalid arguments, input, comparison, or output path. |
+| `3` | A requested gap check failed after the report was written. |
+
+The `3` exit code is opt-in through `--fail-on-unobserved` or `--fail-on-never-observed`. It is based on the complete comparison, not the displayed priority threshold.

capagap-0.1.0/docs/DESIGN.md

@@ -0,0 +1,94 @@
+# Comparison model
+
+## Rule sets and coverage
+
+For a static result `S` and a dynamic result `D`, let `C` contain the static matches whose metadata declares a supported dynamic scope. Library rules are excluded unless explicitly requested.
+
+```text
+observed     = C ∩ D
+unobserved   = C - D
+static-only  = S - C
+dynamic-only = D - S
+coverage     = |observed| / |C|
+```
+
+The unit is a matched capa rule, not a function, instruction, execution path, or percentage of code executed. An empty denominator is reported as `n/a`.
+
+Rules are matched by name. Shared rules with different source SHA-256 digests are flagged as drift. Source digests normalize CRLF to LF before hashing.
+
+## Ruleset manifests
+
+A capa result contains matched rules, not a complete inventory of loaded rules. An absent result therefore does not establish that the rule was available to that run.
+
+A supplied manifest adds a source-consistency check:
+
+1. Every included dynamic match must exist in the manifest with the same source digest, or comparison fails.
+2. Comparable static matches without an exact manifest source match are classified as `ruleset-unverified`.
+3. Unverified rules are excluded from both observed and unobserved coverage counts.
+
+The manifest stores rule names, source digests, scopes, library flags, and relative paths. Its aggregate fingerprint covers sorted rule names and source digests. The metadata reader handles the indented capa rule format without executing YAML tags.
+
+A manifest does not attest to the command, extractor configuration, or full ruleset actually used in a historical run. Preserve those details with the case.
+
+## Input confidence
+
+Matching sample hashes start a comparison at high confidence. Missing hashes lower it to medium. OS, architecture, and capa major-version differences each lower it by one level. Different hashes are rejected unless `--allow-mismatch` is set, in which case confidence is low.
+
+This label describes input consistency, not the reliability of a particular behavioral conclusion.
+
+## Finding priority
+
+The score is deterministic and capped at 100. It combines a baseline with:
+
+- the highest applicable namespace category weight;
+- ATT&CK and MBC mappings;
+- repeated static match locations;
+- a supported process, thread, or call scope; and
+- anti-analysis context from observed matches.
+
+Each factor is included in the finding's reasons. The implementation is in [scoring.py](../src/capagap/scoring.py).
+
+An observed anti-analysis rule gives other gaps a small priority boost. That records a possible lead; it does not establish that the check caused missing behavior.
+
+## Multiple runs
+
+For dynamic results `D₁ … Dₙ`, each comparable static rule has an observation vector:
+
+```text
+observed-in-all       = present in every Dᵢ
+environment-sensitive = present in some, but not all, Dᵢ
+never-observed        = absent from every Dᵢ
+union coverage        = |C ∩ (D₁ ∪ … ∪ Dₙ)| / |C|
+```
+
+The first labeled run is the baseline. Conditions supplied with `--condition` are compared by key and value. Zero or multiple changed keys produce warnings; missing condition declarations also produce warnings. Nothing in the result document proves those declarations are complete.
+
+Runtime-only matches and anti-analysis signals retain the labels of the runs that observed them.
+
+## Address handling
+
+Only unambiguous virtual addresses become portable RVAs:
+
+```text
+absolute match -> address - static image base
+relative match -> address
+other kinds    -> unmappable evidence
+```
+
+Handoff rejects a selection containing absolute matches when the static image base is missing. Importers add RVAs to the current database base, check mapped memory, and reject a known sample-hash mismatch.
+
+Evidence hotspots group findings at the same exact RVA. They are sorted by finding count, aggregate priority, and RVA. The maximum priority is included for reference. No function boundary or control-flow edge is inferred.
+
+## Analyst review
+
+Finding IDs are derived from the rule name and source digest. A separate triage worksheet holds analyst dispositions and notes. Its identity hashes the sample SHA-256 and sorted finding IDs to catch accidental mismatches; it is not a digital signature or a complete case identity.
+
+Applying a worksheet creates a reviewed handoff. IDA and Binary Ninja replace comment lines carrying the corresponding CapaGap marker. Ghidra updates only the Analysis bookmark in the CapaGap category at each location.
+
+## Input handling
+
+CapaGap never executes sample content or embedded rule source. JSON inputs are limited to 256 MiB after decompression. Manifest and worksheet inputs have separate size limits.
+
+Native importer scripts are fixed package resources. Report-controlled text is loaded as JSON data, not inserted into executable source. Manifest, handoff, and triage writes require explicit overwrite flags; ordinary report output replaces an existing destination.
+
+Generated reports can contain sensitive paths, indicators, and analyst notes. They are not redacted automatically.