# j-mazz/sys-scan-graph architecture

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

- Interactive diagram: https://gitdiagram.com/j-mazz/sys-scan-graph
- Repository: https://github.com/j-mazz/sys-scan-graph

## Overview

Sys-Scan-Graph is a host security scanner with a standalone C++ scan path and an optional Python intelligence stage. The main workflow is scan → canonical JSON report → local analysis and enrichment → enriched report or analyst-facing outputs. Python’s pipeline imports the principal analysis stages; the CLI exposes analysis and reporting capabilities. README documentation supplies the cross-process handoff and capabilities not established by sampled implementation. Several scanner internals and UI connections are not shown, so those relationships are omitted.

Main entry points: [`agent/sys_scan_agent/pipeline.py`](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/pipeline.py) (Analysis pipeline), [`agent/sys_scan_agent/cli.py`](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/cli.py) (Agent CLI), [`src/main.cpp`](https://github.com/j-mazz/sys-scan-graph/blob/main/src/main.cpp) (C++ scanner), [`agent/sys_scan_agent/llm.py`](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/llm.py) (Summary generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Host scanning"]
  node_core["C++ scanner<br/>[main.cpp]"]
  node_exec_events["eBPF event probes<br/>[process_exec.bpf.c]"]
  node_raw_report["Canonical scan report"]
end

subgraph group_intelligence["Intelligence pipeline"]
  node_cli["Agent CLI<br/>[cli.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_loader["Report loading<br/>[loader.py]"]
  node_enricher["Finding enrichment<br/>[enricher.py]"]
  node_correlator["Finding correlation<br/>[correlator.py]"]
  node_reduction["Finding reduction<br/>[reduction.py]"]
  node_llm["Summary generation<br/>[llm.py]"]
end

subgraph group_analysis["Analysis services"]
  node_baseline[("Baseline comparison<br/>[baseline.py]")]
  node_rules["Rules and gaps<br/>[rules.py]"]
  node_knowledge["Security knowledge<br/>[knowledge.py]"]
  node_providers["LLM providers<br/>[llm_provider.py]"]
  node_redaction["Data redaction<br/>[redaction.py]"]
  node_config["Agent configuration<br/>[config.py]"]
end

subgraph group_outputs["Reports and operations"]
  node_html["HTML reporting<br/>[report_html.py]"]
  node_metrics["Metrics reporting"]
end

node_operator(("Operator or pipeline"))
node_analyst(("Analysts and pipelines"))

node_operator -->|"runs scan"| node_core
node_core -->|"writes JSON"| node_raw_report
node_raw_report -->|"analyzes report"| node_cli
node_operator -->|"runs analysis"| node_cli
node_cli -->|"dispatches analysis"| node_pipeline
node_pipeline -->|"loads report"| node_loader
node_pipeline -->|"enriches findings"| node_enricher
node_pipeline -->|"correlates findings"| node_correlator
node_pipeline -->|"reduces findings"| node_reduction
node_pipeline -->|"compares baseline"| node_baseline
node_pipeline -->|"reads settings"| node_config
node_pipeline -->|"generates summary"| node_llm
node_llm -->|"uses redaction"| node_redaction
node_cli -->|"loads rules"| node_rules
node_cli -->|"creates HTML"| node_html
node_cli -->|"exports metrics"| node_metrics
node_llm -->|"selects provider"| node_providers
node_cli -->|"delivers outputs"| node_analyst
node_core -.-> node_exec_events

click node_core "https://github.com/j-mazz/sys-scan-graph/blob/main/src/main.cpp"
click node_exec_events "https://github.com/j-mazz/sys-scan-graph/blob/main/src/ebpf/process_exec.bpf.c"
click node_cli "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/cli.py"
click node_pipeline "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/pipeline.py"
click node_loader "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/loader.py"
click node_enricher "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/enricher.py"
click node_correlator "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/correlator.py"
click node_reduction "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/reduction.py"
click node_baseline "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/baseline.py"
click node_rules "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/rules.py"
click node_knowledge "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/knowledge.py"
click node_llm "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/llm.py"
click node_providers "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/llm_provider.py"
click node_redaction "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/redaction.py"
click node_config "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/config.py"
click node_html "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/report_html.py"
click node_metrics "https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/metrics_exporter.py"

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_core,node_exec_events,node_raw_report toneBlue
class node_cli,node_pipeline,node_loader,node_enricher,node_correlator,node_reduction,node_llm toneAmber
class node_baseline,node_rules,node_knowledge,node_providers,node_redaction,node_config toneMint
class node_html,node_metrics toneRose
class node_operator,node_analyst toneIndigo
```

## Components

### Host scanning

- [C++ scanner](https://github.com/j-mazz/sys-scan-graph/blob/main/src/main.cpp): `src/main.cpp`
- [eBPF event probes](https://github.com/j-mazz/sys-scan-graph/blob/main/src/ebpf/process_exec.bpf.c): `src/ebpf/process_exec.bpf.c`
- **Canonical scan report**

### Intelligence pipeline

- [Agent CLI](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/cli.py): `agent/sys_scan_agent/cli.py`
- [Analysis pipeline](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/pipeline.py): `agent/sys_scan_agent/pipeline.py`
- [Report loading](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/loader.py): `agent/sys_scan_agent/loader.py`
- [Finding enrichment](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/enricher.py): `agent/sys_scan_agent/enricher.py`
- [Finding correlation](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/correlator.py): `agent/sys_scan_agent/correlator.py`
- [Finding reduction](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/reduction.py): `agent/sys_scan_agent/reduction.py`
- [Summary generation](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/llm.py): `agent/sys_scan_agent/llm.py`

### Analysis services

- [Baseline comparison](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/baseline.py): `agent/sys_scan_agent/baseline.py`
- [Rules and gaps](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/rules.py): `agent/sys_scan_agent/rules.py`
- [Security knowledge](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/knowledge.py): `agent/sys_scan_agent/knowledge.py`
- [LLM providers](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/llm_provider.py): `agent/sys_scan_agent/llm_provider.py`
- [Data redaction](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/redaction.py): `agent/sys_scan_agent/redaction.py`
- [Agent configuration](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/config.py): `agent/sys_scan_agent/config.py`

### Reports and operations

- [HTML reporting](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/report_html.py): `agent/sys_scan_agent/report_html.py`
- [Metrics reporting](https://github.com/j-mazz/sys-scan-graph/blob/main/agent/sys_scan_agent/metrics_exporter.py): `agent/sys_scan_agent/metrics_exporter.py`

### Other components

- **Operator or pipeline**
- **Analysts and pipelines**

## Connections

- Operator or pipeline → C++ scanner: runs scan (evidence: `README.md`)
- C++ scanner → Canonical scan report: writes JSON (evidence: `README.md`)
- Canonical scan report → Agent CLI: analyzes report (evidence: `README.md`)
- Operator or pipeline → Agent CLI: runs analysis (evidence: `README.md`)
- Agent CLI → Analysis pipeline: dispatches analysis (evidence: `agent/sys_scan_agent/cli.py`)
- Analysis pipeline → Report loading: loads report (evidence: `agent/sys_scan_agent/pipeline.py`)
- Analysis pipeline → Finding enrichment: enriches findings (evidence: `agent/sys_scan_agent/pipeline.py`)
- Analysis pipeline → Finding correlation: correlates findings (evidence: `agent/sys_scan_agent/pipeline.py`)
- Analysis pipeline → Finding reduction: reduces findings (evidence: `agent/sys_scan_agent/pipeline.py`)
- Analysis pipeline → Baseline comparison: compares baseline (evidence: `agent/sys_scan_agent/pipeline.py`)
- Analysis pipeline → Agent configuration: reads settings (evidence: `agent/sys_scan_agent/pipeline.py`)
- Analysis pipeline → Summary generation: generates summary (evidence: `agent/sys_scan_agent/pipeline.py`)
- Summary generation → Data redaction: uses redaction (evidence: `agent/sys_scan_agent/llm.py`)
- Agent CLI → Rules and gaps: loads rules (evidence: `agent/sys_scan_agent/cli.py`)
- Agent CLI → HTML reporting: creates HTML (evidence: `agent/sys_scan_agent/cli.py`)
- Agent CLI → Metrics reporting: exports metrics (evidence: `agent/sys_scan_agent/cli.py`)
- Summary generation → LLM providers: selects provider (evidence: `agent/sys_scan_agent/llm_provider.py`)
- Agent CLI → Analysts and pipelines: delivers outputs (evidence: `README.md`)
- C++ scanner → eBPF event probes
