# akash-billawa/execution-aware-scanner architecture

> Architecture diagram of the GitHub repository akash-billawa/execution-aware-scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akash-billawa/execution-aware-scanner
- Repository: https://github.com/akash-billawa/execution-aware-scanner

## Overview

#### Purpose and Entry Points
This Rust workspace implements an execution-aware vulnerability scanner: it joins image/SBOM CVEs with observed Linux runtime behavior, EPSS/CISA KEV intelligence, risk scoring, attack-path analysis, and optional enforcement. The primary daemon entry point is `scanner-agent/src/main.rs`; a separate aggregation process exists at `scanner-aggregator/src/main.rs`. Shared domain types live in `scanner-common/src/lib.rs`.

#### Runtime Capture Boundary
Linux eBPF programs emit unified security events for process, file/library, network, probe, and tracing activity. Kernel-side sources are in `scanner-ebpf/src/lib.rs`, `scanner-ebpf/src/events.rs`, and `scanner-ebpf/src/tracepoints.rs`. The agent conditionally loads these programs through `scanner-agent/src/bpf_loader.rs`; non-eBPF development uses `scanner-agent/src/bpf_loader_stub.rs`. This is the principal platform boundary: eBPF needs Linux kernel 5.8+, BTF, compatible headers, and privileged capabilities.

#### Event Ingestion and Runtime Evidence
The agent consumes kernel events, converts them into its userspace runtime model, and records execution evidence such as loaded libraries and network activity. The pipeline centers on `scanner-agent/src/event_consumer.rs`, `scanner-agent/src/runtime_mapper.rs`, and `scanner-agent/src/runtime_correlation.rs`. `scanner-agent/src/state.rs` is the in-process state boundary used by downstream analysis; runtime evidence determines whether an otherwise static vulnerable component is reachable.

#### Vulnerability and Intelligence Pipeline
Static software inventory and vulnerability detection originate from image/SBOM inputs and OCI scanning, represented by `scanner-agent/src/sbom.rs`, `scanner-agent/src/oci_scanner.rs`, and `scanner-agent/src/vuln_detector.rs`. Threat intelligence enrichment is handled in `scanner-agent/src/intel.rs`. The resulting vulnerability records are matched against runtime evidence before prioritization, rather than treating all image CVEs as equally actionable.

#### Risk, Graph, and Proof Analysis
Risk evaluation combines CVSS, EPSS, KEV, and runtime reachability using `scanner-agent/src/risk_engine.rs` and `scanner-agent/src/predictive_risk.rs`. Attack-path construction and runtime-oriented correlation are represented by `scanner-agent/src/attack_graph.rs`, `scanner-agent/src/runtime_attack_graph.rs`, and `scanner-agent/src/execution_proof.rs`. This layer converts enriched findings into prioritized, explainable paths and execution-aware findings.

#### Policy and Enforcement Boundary
Policy evaluation is separated from enforcement mechanics: `scanner-agent/src/policy_engine.rs` evaluates policy, including Rego assets under `policies/`, while `scanner-agent/src/enforcement.rs` and `scanner-agent/src/safe_enforcement.rs` apply guarded actions. Network-level controls use `scanner-agent/src/tc_enforcer.rs`; remediation integration is defined by `scanner-agent/proto/remediator.proto` and `scanner-agent/src/remediator.rs`. Enforcement should remain gated by runtime validation and safe/audit modes.

#### Interfaces, Observability, and Deployment
The daemon exposes findings, scans, policies, and webhook-facing APIs under `scanner-agent/src/api/`, with metrics and health endpoints implemented in `scanner-agent/src/metrics.rs`. Outbound notifications are handled by `scanner-agent/src/webhook_sender.rs`; cloud integration adapters exist in `scanner-agent/src/cloud/`. It is deployable as a Kubernetes node-level DaemonSet via `deploy/kubernetes/daemonset.yaml` or the Helm chart at `helm/execution-aware-scanner/`; RBAC and network isolation are explicit in `deploy/kubernetes/rbac.yaml` and `deploy/kubernetes/networkpolicy.yaml`. Grafana dashboards are provisioned from `grafana/`.

Main entry points: [`scanner-agent/src/state.rs`](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/state.rs) (Agent state), [`scanner-agent/src/execution_proof.rs`](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/execution_proof.rs) (Execution proof), [`scanner-agent/src/safe_enforcement.rs`](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/safe_enforcement.rs) (Safe enforcement), [`scanner-agent/src/risk_engine.rs`](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/risk_engine.rs) (Risk engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime capture"]
  node_ebpf{{"eBPF event programs<br/>kernel eBPF<br/>[lib.rs]"}}
  node_bpf_loader["BPF loader<br/>agent adapter<br/>[bpf_loader.rs]"]
  node_event_consumer["Event consumer<br/>ingestion pipeline<br/>[event_consumer.rs]"]
  node_runtime_mapper["Runtime mapper<br/>evidence model<br/>[runtime_mapper.rs]"]
  node_runtime_correlation["Runtime correlation<br/>evidence correlation"]
  node_state[("Agent state<br/>in-process state<br/>[state.rs]")]
end

subgraph group_analysis["Finding analysis"]
  node_sbom["SBOM inventory<br/>software inventory<br/>[sbom.rs]"]
  node_oci_scanner["OCI scanner<br/>image scanner<br/>[oci_scanner.rs]"]
  node_vuln_detector["Vulnerability detection<br/>CVE detection<br/>[vuln_detector.rs]"]
  node_intel["Threat intelligence<br/>EPSS / KEV enrichment<br/>[intel.rs]"]
  node_risk_engine["Risk engine<br/>risk scoring<br/>[risk_engine.rs]"]
  node_attack_graph["Attack-path analysis<br/>attack graph<br/>[attack_graph.rs]"]
  node_execution_proof["Execution proof<br/>finding proof<br/>[execution_proof.rs]"]
end

subgraph group_response["Policy and response"]
  node_policy["Policy engine<br/>policy evaluation<br/>[policy_engine.rs]"]
  node_enforcement["Safe enforcement<br/>guarded actions"]
  node_remediator["Remediation integration<br/>gRPC integration<br/>[remediator.rs]"]
end

subgraph group_interfaces["Interfaces and deployment"]
  node_agent_api["Agent API<br/>daemon API"]
  node_notifications["Webhook notifications<br/>outbound integration<br/>[webhook_sender.rs]"]
  node_agent["Scanner agent<br/>Rust daemon<br/>[main.rs]"]
  node_aggregator["Scanner aggregator<br/>Rust process<br/>[main.rs]"]
  node_daemonset["Kubernetes DaemonSet<br/>deployment manifest<br/>[daemonset.yaml]"]
end

node_common["Shared domain types<br/>Rust crate<br/>[lib.rs]"]

node_common -->|"shared types"| node_agent
node_common -->|"shared types"| node_aggregator
node_agent -->|"initializes"| node_bpf_loader
node_bpf_loader -->|"loads"| node_ebpf
node_ebpf -->|"security events"| node_event_consumer
node_event_consumer -->|"raw events"| node_runtime_mapper
node_runtime_mapper -->|"runtime evidence"| node_runtime_correlation
node_runtime_correlation -->|"correlated evidence"| node_state
node_oci_scanner -->|"image inventory"| node_sbom
node_sbom -->|"components"| node_vuln_detector
node_vuln_detector -->|"vulnerability records"| node_intel
node_intel -->|"enriched CVEs"| node_risk_engine
node_state -->|"runtime reachability"| node_risk_engine
node_risk_engine -->|"prioritized findings"| node_attack_graph
node_state -->|"runtime relationships"| node_attack_graph
node_attack_graph -->|"attack paths"| node_execution_proof
node_execution_proof -->|"explainable findings"| node_policy
node_policy -->|"approved action"| node_enforcement
node_enforcement -->|"remediation request"| node_remediator
node_enforcement -->|"action status"| node_agent_api
node_execution_proof -->|"findings"| node_agent_api
node_agent_api -->|"webhook events"| node_notifications
node_daemonset -->|"deploys"| node_agent

click node_common "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-common/src/lib.rs"
click node_ebpf "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-ebpf/src/lib.rs"
click node_bpf_loader "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/bpf_loader.rs"
click node_event_consumer "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/event_consumer.rs"
click node_runtime_mapper "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/runtime_mapper.rs"
click node_runtime_correlation "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/runtime_correlation.rs"
click node_state "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/state.rs"
click node_sbom "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/sbom.rs"
click node_oci_scanner "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/oci_scanner.rs"
click node_vuln_detector "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/vuln_detector.rs"
click node_intel "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/intel.rs"
click node_risk_engine "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/risk_engine.rs"
click node_attack_graph "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/attack_graph.rs"
click node_execution_proof "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/execution_proof.rs"
click node_policy "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/policy_engine.rs"
click node_enforcement "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/safe_enforcement.rs"
click node_remediator "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/remediator.rs"
click node_notifications "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/webhook_sender.rs"
click node_agent "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/main.rs"
click node_aggregator "https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-aggregator/src/main.rs"
click node_daemonset "https://github.com/akash-billawa/execution-aware-scanner/blob/main/deploy/kubernetes/daemonset.yaml"

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_ebpf,node_bpf_loader,node_event_consumer,node_runtime_mapper,node_runtime_correlation,node_state toneBlue
class node_sbom,node_oci_scanner,node_vuln_detector,node_intel,node_risk_engine,node_attack_graph,node_execution_proof toneAmber
class node_policy,node_enforcement,node_remediator toneMint
class node_agent_api,node_notifications,node_agent,node_aggregator,node_daemonset toneRose
class node_common toneNeutral
```

## Components

### Runtime capture

Linux kernel telemetry and agent-side evidence processing.

- [eBPF event programs](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-ebpf/src/lib.rs): kernel eBPF · Requires supported privileged Linux kernel environment. · `scanner-ebpf/src/lib.rs`
- [BPF loader](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/bpf_loader.rs): agent adapter · Loads eBPF programs; a stub supports non-eBPF development. · `scanner-agent/src/bpf_loader.rs`
- [Event consumer](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/event_consumer.rs): ingestion pipeline · `scanner-agent/src/event_consumer.rs`
- [Runtime mapper](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/runtime_mapper.rs): evidence model · `scanner-agent/src/runtime_mapper.rs`
- [Runtime correlation](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/runtime_correlation.rs): evidence correlation · Relates execution evidence to vulnerable components. · `scanner-agent/src/runtime_correlation.rs`
- [Agent state](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/state.rs): in-process state · State boundary for downstream analysis. · `scanner-agent/src/state.rs`

### Finding analysis

Static inventory, intelligence, risk, and execution-aware proof.

- [SBOM inventory](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/sbom.rs): software inventory · `scanner-agent/src/sbom.rs`
- [OCI scanner](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/oci_scanner.rs): image scanner · `scanner-agent/src/oci_scanner.rs`
- [Vulnerability detection](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/vuln_detector.rs): CVE detection · `scanner-agent/src/vuln_detector.rs`
- [Threat intelligence](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/intel.rs): EPSS / KEV enrichment · `scanner-agent/src/intel.rs`
- [Risk engine](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/risk_engine.rs): risk scoring · Combines CVSS, EPSS, KEV, and reachability. · `scanner-agent/src/risk_engine.rs`
- [Attack-path analysis](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/attack_graph.rs): attack graph · `scanner-agent/src/attack_graph.rs`
- [Execution proof](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/execution_proof.rs): finding proof · Produces explainable execution-aware findings. · `scanner-agent/src/execution_proof.rs`

### Policy and response

Guarded policy decisions and remediation actions.

- [Policy engine](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/policy_engine.rs): policy evaluation · Evaluates policy including Rego assets. · `scanner-agent/src/policy_engine.rs`
- [Safe enforcement](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/safe_enforcement.rs): guarded actions · Applies actions only through runtime validation and safe/audit modes. · `scanner-agent/src/safe_enforcement.rs`
- [Remediation integration](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/remediator.rs): gRPC integration · `scanner-agent/src/remediator.rs`

### Interfaces and deployment

External APIs, notifications, and node-level operation.

- **Agent API**: daemon API · Exposes findings, scans, policies, and webhook-facing APIs.
- [Webhook notifications](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/webhook_sender.rs): outbound integration · `scanner-agent/src/webhook_sender.rs`
- [Scanner agent](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-agent/src/main.rs): Rust daemon · Primary node-level scanner process. · `scanner-agent/src/main.rs`
- [Scanner aggregator](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-aggregator/src/main.rs): Rust process · Separate aggregation process. · `scanner-aggregator/src/main.rs`
- [Kubernetes DaemonSet](https://github.com/akash-billawa/execution-aware-scanner/blob/main/deploy/kubernetes/daemonset.yaml): deployment manifest · Deploys the agent on Kubernetes nodes. · `deploy/kubernetes/daemonset.yaml`

### Other components

- [Shared domain types](https://github.com/akash-billawa/execution-aware-scanner/blob/main/scanner-common/src/lib.rs): Rust crate · `scanner-common/src/lib.rs`

## Connections

- Shared domain types → Scanner agent: shared types
- Shared domain types → Scanner aggregator: shared types
- Scanner agent → BPF loader: initializes
- BPF loader → eBPF event programs: loads
- eBPF event programs → Event consumer: security events
- Event consumer → Runtime mapper: raw events
- Runtime mapper → Runtime correlation: runtime evidence
- Runtime correlation → Agent state: correlated evidence
- OCI scanner → SBOM inventory: image inventory
- SBOM inventory → Vulnerability detection: components
- Vulnerability detection → Threat intelligence: vulnerability records
- Threat intelligence → Risk engine: enriched CVEs
- Agent state → Risk engine: runtime reachability
- Risk engine → Attack-path analysis: prioritized findings
- Agent state → Attack-path analysis: runtime relationships
- Attack-path analysis → Execution proof: attack paths
- Execution proof → Policy engine: explainable findings
- Policy engine → Safe enforcement: approved action
- Safe enforcement → Remediation integration: remediation request
- Safe enforcement → Agent API: action status
- Execution proof → Agent API: findings
- Agent API → Webhook notifications: webhook events
- Kubernetes DaemonSet → Scanner agent: deploys