# samartomar/aih-scan architecture

> Architecture diagram of the GitHub repository samartomar/aih-scan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samartomar/aih-scan
- Repository: https://github.com/samartomar/aih-scan

## Overview

AIH Scanner is a Node.js evidence-producing library and CLI: callers select a detector and source closure, the runner executes analysis, and the package seals, attests, and optionally bundles or projects the resulting evidence. The README also documents detector registration, OCI execution, and a separate bounded baseline-vet/publication capability. Paths identify the owning modules; several subsystem links reflect documented capabilities because their implementation was not sampled.

Main entry points: [`src/runner/run-detector-v1.ts`](https://github.com/samartomar/aih-scan/blob/main/src/runner/run-detector-v1.ts) (Scan runner), [`src/runner/engine-dispatch-v1.ts`](https://github.com/samartomar/aih-scan/blob/main/src/runner/engine-dispatch-v1.ts) (Engine dispatch), [`src/observation/scan-attestation-v2.ts`](https://github.com/samartomar/aih-scan/blob/main/src/observation/scan-attestation-v2.ts) (Scan attestation), [`src/baseline/batch-v1.ts`](https://github.com/samartomar/aih-scan/blob/main/src/baseline/batch-v1.ts) (Baseline vet records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and selection"]
  node_cli["CLI<br/>[cli.ts]"]
  node_capabilities["Detector capabilities"]
  node_registration["Detector registration"]
end

subgraph group_execution["Detector execution"]
  node_runner["Scan runner<br/>[run-detector-v1.ts]"]
  node_dispatch["Engine dispatch"]
  node_runtime["Bounded runtime<br/>[runtime-v1.ts]"]
  node_cisco["Cisco analyzers<br/>[index.ts]"]
  node_mcp["Cisco MCP scanner<br/>[index.ts]"]
  node_snyk["Snyk analyzer<br/>[index.ts]"]
end

subgraph group_evidence["Evidence production"]
  node_observation["Scan observation"]
  node_seals["Source seals<br/>[source-seal-v2.ts]"]
  node_attestation["Scan attestation"]
  node_bundle["Capture bundle<br/>[scan-bundle-v2.ts]"]
  node_findings["Findings projection"]
end

subgraph group_custody["Verification and projection"]
  node_core["Core evidence envelope"]
end

subgraph group_baseline["Baseline evidence"]
  node_baseline["Baseline vet records<br/>[batch-v1.ts]"]
  node_baseline_signature["Baseline signing and verification<br/>[attestation-v1.ts]"]
  node_publication["Baseline publication<br/>[publication-v1.ts]"]
end

node_caller(("Caller"))
node_source["Selected source"]
node_analyzers["Analyzer packages"]
node_trust["Trust roots and policy"]
node_consumer(("Evidence consumer"))

node_caller -->|"invokes"| node_cli
node_caller -->|"requests scan"| node_runner
node_caller -->|"selects closure"| node_source
node_runner -->|"resolves detector"| node_capabilities
node_caller -->|"supplies registration"| node_registration
node_runner -->|"dispatches run"| node_dispatch
node_dispatch -->|"runs engine"| node_runtime
node_dispatch -->|"runs scan"| node_cisco
node_dispatch -->|"runs scan"| node_mcp
node_dispatch -->|"runs scan"| node_snyk
node_runtime -->|"runs analyzer"| node_analyzers
node_dispatch -.->|"runs analyzer"| node_analyzers
node_runner -->|"reads source"| node_source
node_runner -->|"produces evidence"| node_observation
node_runner -->|"seals source"| node_seals
node_observation -->|"attests scan"| node_attestation
node_attestation -->|"writes bundle"| node_bundle
node_bundle -->|"supplies evidence"| node_consumer
node_attestation -->|"verifies against"| node_trust
node_attestation -->|"projects evidence"| node_core
node_attestation -->|"projects findings"| node_findings
node_consumer -->|"requests vet"| node_baseline
node_baseline -->|"signs or verifies"| node_baseline_signature
node_baseline -->|"packs records"| node_publication

click node_cli "https://github.com/samartomar/aih-scan/blob/main/src/cli.ts"
click node_capabilities "https://github.com/samartomar/aih-scan/blob/main/src/capability/detector-capability-v1.ts"
click node_registration "https://github.com/samartomar/aih-scan/blob/main/src/registration/detector-registration-v1.ts"
click node_runner "https://github.com/samartomar/aih-scan/blob/main/src/runner/run-detector-v1.ts"
click node_dispatch "https://github.com/samartomar/aih-scan/blob/main/src/runner/engine-dispatch-v1.ts"
click node_runtime "https://github.com/samartomar/aih-scan/blob/main/src/baseline/runtime-v1.ts"
click node_cisco "https://github.com/samartomar/aih-scan/blob/main/src/detectors/cisco-multi-skill/index.ts"
click node_mcp "https://github.com/samartomar/aih-scan/blob/main/src/detectors/cisco-mcp-scanner/index.ts"
click node_snyk "https://github.com/samartomar/aih-scan/blob/main/src/detectors/snyk-agent-scan/index.ts"
click node_analyzers "https://github.com/samartomar/aih-scan/tree/main/tools/baseline-analyzers"
click node_observation "https://github.com/samartomar/aih-scan/blob/main/src/observation/observation-evidence-v1.ts"
click node_seals "https://github.com/samartomar/aih-scan/blob/main/src/observation/source-seal-v2.ts"
click node_attestation "https://github.com/samartomar/aih-scan/blob/main/src/observation/scan-attestation-v2.ts"
click node_bundle "https://github.com/samartomar/aih-scan/blob/main/src/observation/scan-bundle-v2.ts"
click node_findings "https://github.com/samartomar/aih-scan/blob/main/src/findings/scan-findings-v1.ts"
click node_core "https://github.com/samartomar/aih-scan/blob/main/src/core/organization-evidence-envelope-v1.ts"
click node_baseline "https://github.com/samartomar/aih-scan/blob/main/src/baseline/batch-v1.ts"
click node_baseline_signature "https://github.com/samartomar/aih-scan/blob/main/src/baseline/attestation-v1.ts"
click node_publication "https://github.com/samartomar/aih-scan/blob/main/src/baseline/publication-v1.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_capabilities,node_registration toneBlue
class node_runner,node_dispatch,node_runtime,node_cisco,node_mcp,node_snyk toneAmber
class node_observation,node_seals,node_attestation,node_bundle,node_findings toneMint
class node_core toneRose
class node_baseline,node_baseline_signature,node_publication,node_caller,node_source,node_trust,node_consumer toneIndigo
class node_analyzers toneTeal
```

## Components

### Entry and selection

- [CLI](https://github.com/samartomar/aih-scan/blob/main/src/cli.ts): `src/cli.ts`
- [Detector capabilities](https://github.com/samartomar/aih-scan/blob/main/src/capability/detector-capability-v1.ts): `src/capability/detector-capability-v1.ts`
- [Detector registration](https://github.com/samartomar/aih-scan/blob/main/src/registration/detector-registration-v1.ts): `src/registration/detector-registration-v1.ts`

### Detector execution

- [Scan runner](https://github.com/samartomar/aih-scan/blob/main/src/runner/run-detector-v1.ts): `src/runner/run-detector-v1.ts`
- [Engine dispatch](https://github.com/samartomar/aih-scan/blob/main/src/runner/engine-dispatch-v1.ts): `src/runner/engine-dispatch-v1.ts`
- [Bounded runtime](https://github.com/samartomar/aih-scan/blob/main/src/baseline/runtime-v1.ts): `src/baseline/runtime-v1.ts`
- [Cisco analyzers](https://github.com/samartomar/aih-scan/blob/main/src/detectors/cisco-multi-skill/index.ts): `src/detectors/cisco-multi-skill/index.ts`
- [Cisco MCP scanner](https://github.com/samartomar/aih-scan/blob/main/src/detectors/cisco-mcp-scanner/index.ts): `src/detectors/cisco-mcp-scanner/index.ts`
- [Snyk analyzer](https://github.com/samartomar/aih-scan/blob/main/src/detectors/snyk-agent-scan/index.ts): `src/detectors/snyk-agent-scan/index.ts`

### Evidence production

- [Scan observation](https://github.com/samartomar/aih-scan/blob/main/src/observation/observation-evidence-v1.ts): `src/observation/observation-evidence-v1.ts`
- [Source seals](https://github.com/samartomar/aih-scan/blob/main/src/observation/source-seal-v2.ts): `src/observation/source-seal-v2.ts`
- [Scan attestation](https://github.com/samartomar/aih-scan/blob/main/src/observation/scan-attestation-v2.ts): `src/observation/scan-attestation-v2.ts`
- [Capture bundle](https://github.com/samartomar/aih-scan/blob/main/src/observation/scan-bundle-v2.ts): `src/observation/scan-bundle-v2.ts`
- [Findings projection](https://github.com/samartomar/aih-scan/blob/main/src/findings/scan-findings-v1.ts): `src/findings/scan-findings-v1.ts`

### Verification and projection

- [Core evidence envelope](https://github.com/samartomar/aih-scan/blob/main/src/core/organization-evidence-envelope-v1.ts): `src/core/organization-evidence-envelope-v1.ts`

### Baseline evidence

- [Baseline vet records](https://github.com/samartomar/aih-scan/blob/main/src/baseline/batch-v1.ts): `src/baseline/batch-v1.ts`
- [Baseline signing and verification](https://github.com/samartomar/aih-scan/blob/main/src/baseline/attestation-v1.ts): `src/baseline/attestation-v1.ts`
- [Baseline publication](https://github.com/samartomar/aih-scan/blob/main/src/baseline/publication-v1.ts): `src/baseline/publication-v1.ts`

### Other components

- **Caller**
- **Selected source**
- [Analyzer packages](https://github.com/samartomar/aih-scan/tree/main/tools/baseline-analyzers): `tools/baseline-analyzers`
- **Trust roots and policy**
- **Evidence consumer**

## Connections

- Caller → CLI: invokes
- Caller → Scan runner: requests scan
- Caller → Selected source: selects closure
- Scan runner → Detector capabilities: resolves detector
- Caller → Detector registration: supplies registration
- Scan runner → Engine dispatch: dispatches run
- Engine dispatch → Bounded runtime: runs engine
- Engine dispatch → Cisco analyzers: runs scan
- Engine dispatch → Cisco MCP scanner: runs scan
- Engine dispatch → Snyk analyzer: runs scan
- Bounded runtime → Analyzer packages: runs analyzer
- Engine dispatch → Analyzer packages: runs analyzer
- Scan runner → Selected source: reads source
- Scan runner → Scan observation: produces evidence
- Scan runner → Source seals: seals source
- Scan observation → Scan attestation: attests scan
- Scan attestation → Capture bundle: writes bundle
- Capture bundle → Evidence consumer: supplies evidence
- Scan attestation → Trust roots and policy: verifies against
- Scan attestation → Core evidence envelope: projects evidence
- Scan attestation → Findings projection: projects findings
- Evidence consumer → Baseline vet records: requests vet
- Baseline vet records → Baseline signing and verification: signs or verifies
- Baseline vet records → Baseline publication: packs records