# dhruvnavadiya0/security-signal-engine architecture

> Architecture diagram of the GitHub repository dhruvnavadiya0/security-signal-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhruvnavadiya0/security-signal-engine
- Repository: https://github.com/dhruvnavadiya0/security-signal-engine

## Overview

Security Signal Engine is a security-scanning and finding-prioritization platform. Its principal workflow accepts a local codebase or live URL through the CLI or REST API, dispatches scanners, normalizes and deduplicates findings, scores risk, enriches findings with an optional local LLM or deterministic fallback, and generates reports. The graph also preserves the documented evaluation, plugin, and URL-scanning capabilities. Edges follow the pipeline excerpt, source-index references, or README; unsampled internals are not treated as inspected.

Main entry points: [`security-signal-engine/src/pipeline.py`](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/pipeline.py) (Scan pipeline), [`security-signal-engine/src/scanners/url_scanner.py`](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/url_scanner.py) (URL scanner), [`security-signal-engine/src/scanners/orchestrator.py`](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/orchestrator.py) (Scanner orchestrator), [`security-signal-engine/src/cli.py`](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["REST API<br/>[main.py]"]
  node_pipeline["Scan pipeline<br/>[pipeline.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_scanning["Scanning"]
  node_orchestrator["Scanner orchestrator<br/>[orchestrator.py]"]
  node_semgrep["Semgrep adapter<br/>[semgrep.py]"]
  node_urlscanner["URL scanner<br/>[url_scanner.py]"]
  node_plugin["Plugin manager<br/>[plugin_manager.py]"]
  node_crawler["Smart crawler<br/>[smart_crawler.py]"]
  node_rate["Rate limiter"]
  node_traffic[("Traffic store<br/>[traffic_store.py]")]
  node_oast["OAST detector<br/>[oast_detector.py]"]
end

subgraph group_analysis["Finding analysis"]
  node_schemas["Finding schemas<br/>[schemas.py]"]
  node_normalization["Normalization<br/>[engine.py]"]
  node_filter["False-positive filter"]
  node_dedup["Deduplication<br/>[engine.py]"]
  node_scoring["Risk scoring<br/>[engine.py]"]
  node_owasp["OWASP evaluation<br/>[owasp.py]"]
end

subgraph group_enrichment["Explanation"]
  node_intelligence["LLM intelligence<br/>[intelligence.py]"]
  node_llmclient["Ollama client<br/>[client.py]"]
  node_fallback["Deterministic fallback<br/>[fallback.py]"]
end

subgraph group_outputs["Reports"]
  node_cli_report["CLI report<br/>[cli_report.py]"]
  node_json_report["JSON report<br/>[json_report.py]"]
  node_pdf_report["PDF report<br/>[pdf_report.py]"]
  node_sarif_report["SARIF report<br/>[sarif_report.py]"]
end

node_user(("Security engineer"))
node_ollama(("Ollama service"))

node_user -->|"runs scan"| node_cli
node_user -->|"requests scan"| node_api
node_cli -->|"runs"| node_pipeline
node_api -->|"runs"| node_pipeline
node_cli -->|"loads settings"| node_config
node_pipeline -->|"builds configuration"| node_config
node_pipeline -->|"runs scanners"| node_orchestrator
node_orchestrator -->|"dispatches"| node_semgrep
node_orchestrator -->|"dispatches"| node_urlscanner
node_orchestrator -->|"loads plugins"| node_plugin
node_urlscanner -->|"uses"| node_crawler
node_urlscanner -->|"uses"| node_rate
node_urlscanner -->|"uses"| node_traffic
node_urlscanner -->|"uses"| node_oast
node_pipeline -->|"filters findings"| node_filter
node_pipeline -->|"normalizes"| node_normalization
node_pipeline -->|"deduplicates"| node_dedup
node_pipeline -->|"scores risk"| node_scoring
node_pipeline -->|"enriches findings"| node_intelligence
node_intelligence -->|"requests generation"| node_llmclient
node_intelligence -->|"uses fallback"| node_fallback
node_llmclient -->|"sends requests"| node_ollama
node_pipeline -.->|"generates report"| node_cli_report
node_pipeline -.->|"generates report"| node_json_report
node_pipeline -->|"generates PDF"| node_pdf_report
node_pipeline -.->|"generates report"| node_sarif_report
node_api -->|"generates PDF"| node_pdf_report
node_owasp -.->|"evaluates scans"| node_pipeline
node_normalization -->|"creates findings"| node_schemas
node_scoring -->|"scores findings"| node_schemas

click node_cli "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/cli.py"
click node_api "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/api/main.py"
click node_pipeline "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/pipeline.py"
click node_config "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/config.py"
click node_orchestrator "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/orchestrator.py"
click node_semgrep "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/semgrep.py"
click node_urlscanner "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/url_scanner.py"
click node_plugin "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/plugin_manager.py"
click node_crawler "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/smart_crawler.py"
click node_rate "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/adaptive_rate_limiter.py"
click node_traffic "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/traffic_store.py"
click node_oast "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/oast_detector.py"
click node_schemas "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/models/schemas.py"
click node_normalization "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/normalization/engine.py"
click node_filter "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/false_positive_filter.py"
click node_dedup "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/dedup/engine.py"
click node_scoring "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scoring/engine.py"
click node_owasp "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/evaluation/owasp.py"
click node_intelligence "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/llm/intelligence.py"
click node_llmclient "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/llm/client.py"
click node_fallback "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/llm/fallback.py"
click node_cli_report "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/cli_report.py"
click node_json_report "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/json_report.py"
click node_pdf_report "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/pdf_report.py"
click node_sarif_report "https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/sarif_report.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_cli,node_api,node_pipeline,node_config toneBlue
class node_orchestrator,node_semgrep,node_urlscanner,node_plugin,node_crawler,node_rate,node_traffic,node_oast toneAmber
class node_schemas,node_normalization,node_filter,node_dedup,node_scoring,node_owasp toneMint
class node_intelligence,node_llmclient,node_fallback toneRose
class node_cli_report,node_json_report,node_pdf_report,node_sarif_report,node_user,node_ollama toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/cli.py): `security-signal-engine/src/cli.py`
- [REST API](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/api/main.py): `security-signal-engine/src/api/main.py`
- [Scan pipeline](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/pipeline.py): `security-signal-engine/src/pipeline.py`
- [Configuration](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/config.py): `security-signal-engine/src/config.py`

### Scanning

- [Scanner orchestrator](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/orchestrator.py): `security-signal-engine/src/scanners/orchestrator.py`
- [Semgrep adapter](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/semgrep.py): `security-signal-engine/src/scanners/semgrep.py`
- [URL scanner](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/url_scanner.py): `security-signal-engine/src/scanners/url_scanner.py`
- [Plugin manager](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/plugin_manager.py): `security-signal-engine/src/scanners/plugin_manager.py`
- [Smart crawler](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/smart_crawler.py): `security-signal-engine/src/scanners/smart_crawler.py`
- [Rate limiter](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/adaptive_rate_limiter.py): `security-signal-engine/src/scanners/adaptive_rate_limiter.py`
- [Traffic store](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/traffic_store.py): `security-signal-engine/src/scanners/traffic_store.py`
- [OAST detector](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/oast_detector.py): `security-signal-engine/src/scanners/oast_detector.py`

### Finding analysis

- [Finding schemas](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/models/schemas.py): `security-signal-engine/src/models/schemas.py`
- [Normalization](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/normalization/engine.py): `security-signal-engine/src/normalization/engine.py`
- [False-positive filter](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scanners/false_positive_filter.py): `security-signal-engine/src/scanners/false_positive_filter.py`
- [Deduplication](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/dedup/engine.py): `security-signal-engine/src/dedup/engine.py`
- [Risk scoring](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/scoring/engine.py): `security-signal-engine/src/scoring/engine.py`
- [OWASP evaluation](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/evaluation/owasp.py): `security-signal-engine/src/evaluation/owasp.py`

### Explanation

- [LLM intelligence](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/llm/intelligence.py): `security-signal-engine/src/llm/intelligence.py`
- [Ollama client](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/llm/client.py): `security-signal-engine/src/llm/client.py`
- [Deterministic fallback](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/llm/fallback.py): `security-signal-engine/src/llm/fallback.py`

### Reports

- [CLI report](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/cli_report.py): `security-signal-engine/src/reports/cli_report.py`
- [JSON report](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/json_report.py): `security-signal-engine/src/reports/json_report.py`
- [PDF report](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/pdf_report.py): `security-signal-engine/src/reports/pdf_report.py`
- [SARIF report](https://github.com/dhruvnavadiya0/security-signal-engine/blob/main/security-signal-engine/src/reports/sarif_report.py): `security-signal-engine/src/reports/sarif_report.py`

### Other components

- **Security engineer**
- **Ollama service**

## Connections

- Security engineer → CLI: runs scan
- Security engineer → REST API: requests scan
- CLI → Scan pipeline: runs (evidence: `security-signal-engine/src/cli.py`)
- REST API → Scan pipeline: runs (evidence: `security-signal-engine/src/api/main.py`)
- CLI → Configuration: loads settings (evidence: `security-signal-engine/src/cli.py`)
- Scan pipeline → Configuration: builds configuration (evidence: `security-signal-engine/src/pipeline.py`)
- Scan pipeline → Scanner orchestrator: runs scanners (evidence: `security-signal-engine/src/pipeline.py`)
- Scanner orchestrator → Semgrep adapter: dispatches (evidence: `security-signal-engine/src/scanners/orchestrator.py`)
- Scanner orchestrator → URL scanner: dispatches (evidence: `security-signal-engine/src/scanners/orchestrator.py`)
- Scanner orchestrator → Plugin manager: loads plugins (evidence: `security-signal-engine/src/scanners/orchestrator.py`)
- URL scanner → Smart crawler: uses (evidence: `security-signal-engine/src/scanners/url_scanner.py`)
- URL scanner → Rate limiter: uses (evidence: `security-signal-engine/src/scanners/url_scanner.py`)
- URL scanner → Traffic store: uses (evidence: `security-signal-engine/src/scanners/url_scanner.py`)
- URL scanner → OAST detector: uses (evidence: `security-signal-engine/src/scanners/url_scanner.py`)
- Scan pipeline → False-positive filter: filters findings (evidence: `security-signal-engine/src/pipeline.py`)
- Scan pipeline → Normalization: normalizes (evidence: `security-signal-engine/src/pipeline.py`)
- Scan pipeline → Deduplication: deduplicates (evidence: `security-signal-engine/src/pipeline.py`)
- Scan pipeline → Risk scoring: scores risk (evidence: `security-signal-engine/src/pipeline.py`)
- Scan pipeline → LLM intelligence: enriches findings (evidence: `security-signal-engine/src/pipeline.py`)
- LLM intelligence → Ollama client: requests generation (evidence: `security-signal-engine/src/llm/intelligence.py`)
- LLM intelligence → Deterministic fallback: uses fallback (evidence: `security-signal-engine/src/llm/intelligence.py`)
- Ollama client → Ollama service: sends requests (evidence: `security-signal-engine/src/llm/client.py`)
- Scan pipeline → CLI report: generates report
- Scan pipeline → JSON report: generates report
- Scan pipeline → PDF report: generates PDF (evidence: `security-signal-engine/src/pipeline.py`)
- Scan pipeline → SARIF report: generates report
- REST API → PDF report: generates PDF (evidence: `security-signal-engine/src/api/main.py`)
- OWASP evaluation → Scan pipeline: evaluates scans
- Normalization → Finding schemas: creates findings (evidence: `security-signal-engine/src/normalization/engine.py`)
- Risk scoring → Finding schemas: scores findings (evidence: `security-signal-engine/src/scoring/engine.py`)
