SKILL.md

# SKILL.md

This file defines practical skills an AI agent should apply when working on `blint`.

## Skill: Navigate blint architecture quickly

- Start at `blint/cli.py` to identify mode (`default`, `sbom`, `db`).
- Follow orchestration in `blint/lib/runners.py`.
- For extraction logic, use `blint/lib/binary.py` and `blint/lib/android.py`.
- For rule behavior, use `blint/lib/analysis.py` and `blint/data/annotations/*.yml`.
- For SBOM behavior, use `blint/lib/sbom.py` and `blint/cyclonedx/spec.py`.

## Skill: Implement rule-driven behavior safely

- Understand rule types:
  - `rules.yml` -> hardening checks (`run_checks`).
  - annotations -> reviews (`METHOD_REVIEWS`, `SYMBOL_REVIEWS`, etc.).
  - `FUNCTION_REVIEWS` -> disassembly-derived behavior checks.
- Keep rule IDs stable and unique.
- Match field paths used in `function_metric` with actual metadata shape.
- Respect evidence limits (`EVIDENCE_LIMIT`) to avoid noisy output.

## Skill: Work with binary metadata extraction

- Preserve format-specific fields while maintaining normalized top-level fields.
- Do not break keys used downstream by checks/reviews/SBOM mappers.
- Keep defensive parsing style: suppress parser exceptions where already expected.
- Validate changes against representative fixtures in `tests/data/*.json` and `tests/data/*.wasm`.

## Skill: Extend disassembly analytics

- `--disassemble` is optional; do not force it into default flows.
- Avoid architecture-specific regressions:
  - x86/x64
  - AArch64/ARM64
  - MIPS/microMIPS/MIPS16 fallback paths
- Keep heuristics lightweight and deterministic.
- Ensure new indicators are configurable/constants-based when possible.

## Skill: Maintain SBOM correctness

- Preserve CycloneDX output validity (spec 1.6 model in this repo).
- Ensure each component has a stable `bom_ref`.
- Avoid dependency self-loops.
- Keep deep-mode details in properties, not default minimal output.
- Respect `--stdout` and output path behavior.
- Remember that `blint sbom --use-blintdb --deep` auto-enables disassembly. Test that path explicitly when changing SBOM or DB matching logic.

## Skill: Use blintdb integration properly

- Database usage is optional and should not block core execution.
- Keep behavior safe when DB is missing or download fails.
- Prefer the local query contract in `blint/db.py` over importing runtime helpers from `blint-db`.
- Use project-level evidence from symbols, binary-name hints, and disassembly hashes together.
- Keep symbol-only matching conservative. Strong exact matches are better than noisy broad guesses.
- Filter tiny or generic hash evidence when it creates cross-project collisions.
- Avoid introducing non-read-only DB access in analysis paths.

## Skill: Testing and validation expectations

- Core tests:
  - `tests/test_analysis.py`
  - `tests/test_binary.py`
  - `tests/test_android.py`
  - `tests/test_disassembler.py`
- Add fixture-based tests for parser/rule changes.
- Prefer narrow tests for one behavior change at a time.
- For `blint/db.py` or `blint/lib/sbom.py` changes, run both fixture tests and one small real corpus build from the linked `blint-db` repo.
- Validate both modes for real corpus checks:
  - symbol-only: `blint sbom --use-blintdb`
  - disassembly-assisted: `blint sbom --use-blintdb --deep`
- For exact binaries that were used to build the corpus, expect near-exact component identification and inspect `internal:blintdb_*` properties when debugging drift.
- Prefer the scripted validation flow in `tests/scripts/validate_blintdb_small_corpus.py` over one-off shell snippets. The selector manifest is versioned in `tests/data/blintdb-small-corpus.json`.

## Skill: Documentation updates with code changes

- Update `docs/RULES.md` when rule schema/usage changes.
- Update `docs/METADATA.md` when metadata keys/meaning change.
- Update `docs/DISASSEMBLE.md` when disassembly fields/heuristics change.
- Keep README examples aligned with actual CLI flags.
- Update `AGENTS.md` and `SKILL.md` when the maintenance workflow changes in a meaningful way.

## Skill: High-confidence change checklist

- Confirm changed fields are consumed correctly by:
  - checks
  - reviews
  - report exporters
  - SBOM generation
- Run tests after editing Python logic.
- Ensure no accidental behavior change in non-targeted binary formats.
- For WASM parsing changes, verify both normalized fields (`imports`, `dynamic_entries`, `functions`) and raw passthrough fields (`wasm_report`, `wasm_analysis`).