# Repository software and cryptographic BOM reports

## Purpose and scope

Use this procedure only for an explicit request to inventory an authorized GitHub
repository. Both Miegyver and Thinker use the same shared tools and procedure.
Record the current requester's identity, repository, requested revision and
intended report audience. Never treat a display name as operator authorization.

The approved implementation has two stages:

- Trivy produces a CycloneDX software BOM and a JSON vulnerability report.
- Local Semgrep rules produce a CycloneDX 1.6 cryptographic BOM containing
  **static algorithm/API candidates** for Go, Python and JavaScript/TypeScript.

Trivy's software BOM is not a cryptographic BOM. Do not rename it or claim it
inventories cryptographic assets. The crypto scanner does not extract keys,
certificates, secrets or source snippets. It does not trace runtime behavior,
resolve all aliases/wrappers, prove reachability, inventory dependency internals
or certify compliance/quantum safety. AES/RSA findings do not establish key sizes,
modes, safety or actual use. MD5/SHA-1 candidates require contextual review;
they are not automatically exploitable vulnerabilities.

## Required capabilities

Read this SOP and `tools/bom-reports/runner.py` /
`tools/bom-reports/crypto-rules.yaml` only when the task needs BOM scanning.
Invoke the dedicated `bom-scanner` MCP tools; never enable `exec` or run scripts
from a repository to work around denied tools.

The service must be deployed with pinned Trivy/Semgrep, matching hash-verified
R2 tool files, operator-approved repository scope and operator-managed credentials.
Scope can list exact repositories or `owner/*` for all repositories under that
exact owner, subject to the scanner GitHub token's repository permissions.
Always submit a concrete `owner/repository`, never a wildcard scan request.
If any requirement is unavailable, say the scan is blocked. Files being present
in local-kb does not make an MCP tool available.

The GitHub MCP is useful for repository/ref discovery. Its current tools read
files and do not clone into agent workspaces. The scanner retrieves an immutable
GitHub source archive with its own read-only credential. Archive extraction and
tool caches use isolated filesystem scratch storage, **not R2 agent temp/**.
Never request or expose the credential, fetch arbitrary URLs, install project
dependencies, build code, execute tests/hooks, or scan a repository outside the
operator allowlist.

## Procedure

1. Confirm `owner/repository`, branch/tag/commit, scope and audience. If scope is
   ambiguous, clarify before retrieval. A source scan does not cover a built
   container image or files generated by a build.
2. Discover exact tools with `tool_search` / `tool_describe`. Expected exposed
   names are `bom-scanner__scan_repository`, `bom-scanner__scan_status` and
   `bom-scanner__read_report`; discovery is not proof of authorization.
3. Call `scan_repository` with `repository` and `ref`. Save its `scan_id` against
   this request. It queues bounded work and returns immediately.
4. Poll `scan_status` without tight loops. Wait for `completed` before claiming
   results. `failed`, queue limits, unknown/interrupted jobs and missing files
   are errors, not empty successful scans. Do not recreate repeated failed jobs
   without new evidence. A restart can interrupt queued/in-progress work.
5. Read `summary.json` first. Confirm the exact resolved Git commit SHA and
   recorded scanner versions. Then read only needed pages of the other reports,
   using returned offsets and checksum metadata. Avoid pasting whole BOMs into
   the conversation or saturating the agent context.
6. Completed files are shared at `local-kb/reports/bom/<scan_id>/`:
   `sbom.cdx.json`, `cbom.cdx.json`, `vulnerabilities.json`, `summary.json`,
   and an operator-readable `manifest.json` with SHA256 checksums. Reports become
   complete only after the manifest is written. Never use a partial directory
   as evidence of successful completion.
7. Return a concise report: requester/project/revision, software component count,
   vulnerability severities, observed crypto algorithms, file/line evidence,
   scanner versions, limitations, and report paths/checksums. Review weaknesses
   in context and distinguish facts, suspected issues and unknowns.
8. Deliver only to the intended shared-channel audience. Report metadata may
   disclose private repository/dependency details. Shared R2 access and the
   scanner bearer credential are not per-user authorization or private storage.
   Follow normal secret/PII rules. Do not publish raw Semgrep output or matched
   source. Propose remediations; do not mutate GitHub, requirements or code.

## Empty or incomplete findings

Zero crypto components means **no supported API candidates detected by these
rules**, not "no cryptography". Dynamic algorithm selection, wrappers, unsupported
libraries and generated/vendor code are outside coverage. Parser errors fail the
crypto scan rather than producing an apparently complete empty CBOM. Zero Trivy
vulnerabilities is limited to detected source dependencies and available advisory
data; missing lockfiles/build outputs reduce completeness.
Check `crypto_files_scanned` and `crypto_exclusions` in the summary. Semgrep's
ignore policy/defaults, oversized files, `node_modules` and `vendor` can exclude
sources; zero scanned files is a coverage warning, never a clean crypto verdict.

## Operator maintenance

Update reviewed source files and scanner image together; a mismatched R2 bundle
fails health checks and new scans. The service does not execute arbitrary newly
uploaded KB code. Keep scratch/cache directories off R2, bound concurrency/size,
and preserve completed report files. Apply retention through an approved
operator workflow, never broad deletion of the KB or agent workspaces.