# m-ali1122/security-incident-triage-assistant architecture

> Architecture diagram of the GitHub repository m-ali1122/security-incident-triage-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m-ali1122/security-incident-triage-assistant
- Repository: https://github.com/m-ali1122/security-incident-triage-assistant

## Overview

This is a security incident triage assistant: it turns a Markdown data pack of logs and operational tables into cited, rule-derived incident findings, severity, notifications, and runbook actions. The main user path is through the web UI and API: startup builds a fact store; questions are routed and answered from verified facts, with optional LLM wording and validated template fallback. Users can also read an LLM-free report or submit batch questions. The README documents the high-level stages; some subsystem links below are based on that documentation rather than sampled implementation.

Main entry points: [`triage/answer/pipeline.py`](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/pipeline.py) (Answer pipeline), [`triage/facts.py`](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/facts.py) (Fact store), [`triage/rules/engine.py`](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/engine.py) (Rule engine), [`triage/api.py`](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/api.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_table_loaders["Table loaders<br/>[tables.py]"]
  node_coverage["Coverage model<br/>[coverage.py]"]
  node_log_parser["Log parser<br/>[logs.py]"]
  node_models["Evidence contracts<br/>[models.py]"]
  node_fact_store[("Fact store<br/>[facts.py]")]
end

subgraph group_analysis["Incident analysis"]
  node_evidence_graph["Evidence graph<br/>[build.py]"]
  node_clustering["Incident clustering<br/>[cluster.py]"]
  node_detectors["Rule detectors<br/>[detectors.py]"]
  node_rule_engine["Rule engine<br/>[engine.py]"]
  node_severity["Severity scoring<br/>[severity.py]"]
  node_calendar["Change calendar checks<br/>[calendar.py]"]
  node_escalation["Escalation contacts<br/>[escalation.py]"]
  node_runbooks["Runbook actions<br/>[runbooks.py]"]
end

subgraph group_answers["Answers and reports"]
  node_report["Incident report<br/>[report.py]"]
  node_router["Question router<br/>[router.py]"]
  node_bundle["Verified fact bundle<br/>[bundle.py]"]
  node_answer_pipeline["Answer pipeline<br/>[pipeline.py]"]
  node_anonymizer["Prompt anonymizer<br/>[anonymize.py]"]
  node_validator["Answer validator<br/>[validate.py]"]
  node_templates["Template fallback<br/>[templates.py]"]
end

subgraph group_runtime["Serving and clients"]
  node_api["HTTP API<br/>[api.py]"]
  node_web["Web interface<br/>[app.js]"]
  node_batch["Batch questions<br/>[batch.py]"]
end

subgraph group_language["LLM wording"]
  node_llm_pool["LLM provider pool<br/>[pool.py]"]
end

node_user(("Analyst"))
node_pack["Incident data pack"]
node_llm_service{{"LLM providers"}}

node_user -->|"asks questions"| node_web
node_web -->|"sends requests"| node_api
node_pack -->|"loads tables"| node_table_loaders
node_pack -->|"parses logs"| node_log_parser
node_table_loaders -->|"provides coverage data"| node_coverage
node_config -->|"configures paths"| node_fact_store
node_fact_store -->|"parses events"| node_log_parser
node_fact_store -->|"loads tables"| node_table_loaders
node_fact_store -->|"builds findings"| node_rule_engine
node_log_parser -->|"creates events"| node_models
node_table_loaders -->|"creates typed records"| node_models
node_fact_store -->|"builds graph"| node_evidence_graph
node_rule_engine -->|"runs checks"| node_detectors
node_rule_engine -->|"clusters findings"| node_clustering
node_rule_engine -->|"scores incidents"| node_severity
node_rule_engine -->|"selects contacts"| node_escalation
node_rule_engine -->|"selects actions"| node_runbooks
node_detectors -->|"checks changes"| node_calendar
node_api -->|"serves facts"| node_fact_store
node_api -->|"answers questions"| node_answer_pipeline
node_api -->|"serves report"| node_report
node_batch -->|"loads facts"| node_fact_store
node_batch -->|"answers questions"| node_answer_pipeline
node_answer_pipeline -->|"routes question"| node_router
node_answer_pipeline -->|"builds fact bundle"| node_bundle
node_answer_pipeline -->|"anonymizes prompt"| node_anonymizer
node_answer_pipeline -->|"requests wording"| node_llm_pool
node_answer_pipeline -->|"validates answer"| node_validator
node_answer_pipeline -->|"falls back"| node_templates
node_llm_pool -->|"calls providers"| node_llm_service
node_answer_pipeline -->|"reads verified facts"| node_fact_store

click node_config "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/config.py"
click node_table_loaders "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/parsers/tables.py"
click node_coverage "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/parsers/coverage.py"
click node_log_parser "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/parsers/logs.py"
click node_models "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/models.py"
click node_fact_store "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/facts.py"
click node_evidence_graph "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/graph/build.py"
click node_clustering "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/graph/cluster.py"
click node_detectors "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/detectors.py"
click node_rule_engine "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/engine.py"
click node_severity "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/severity.py"
click node_calendar "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/calendar.py"
click node_escalation "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/escalation.py"
click node_runbooks "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/runbooks.py"
click node_report "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/report.py"
click node_router "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/router.py"
click node_bundle "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/bundle.py"
click node_answer_pipeline "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/pipeline.py"
click node_anonymizer "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/anonymize.py"
click node_validator "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/validate.py"
click node_templates "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/templates.py"
click node_api "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/api.py"
click node_web "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/web/app.js"
click node_batch "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/batch.py"
click node_llm_pool "https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/llm/pool.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_config,node_table_loaders,node_coverage,node_log_parser,node_models,node_fact_store toneBlue
class node_evidence_graph,node_clustering,node_detectors,node_rule_engine,node_severity,node_calendar,node_escalation,node_runbooks toneAmber
class node_report,node_router,node_bundle,node_answer_pipeline,node_anonymizer,node_validator,node_templates toneMint
class node_api,node_web,node_batch toneRose
class node_llm_pool,node_user,node_pack,node_llm_service toneIndigo
```

## Components

### Data ingestion

- [Runtime configuration](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/config.py): `triage/config.py`
- [Table loaders](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/parsers/tables.py): `triage/parsers/tables.py`
- [Coverage model](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/parsers/coverage.py): `triage/parsers/coverage.py`
- [Log parser](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/parsers/logs.py): `triage/parsers/logs.py`
- [Evidence contracts](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/models.py): `triage/models.py`
- [Fact store](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/facts.py): `triage/facts.py`

### Incident analysis

- [Evidence graph](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/graph/build.py): `triage/graph/build.py`
- [Incident clustering](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/graph/cluster.py): `triage/graph/cluster.py`
- [Rule detectors](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/detectors.py): `triage/rules/detectors.py`
- [Rule engine](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/engine.py): `triage/rules/engine.py`
- [Severity scoring](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/severity.py): `triage/rules/severity.py`
- [Change calendar checks](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/calendar.py): `triage/rules/calendar.py`
- [Escalation contacts](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/escalation.py): `triage/rules/escalation.py`
- [Runbook actions](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/rules/runbooks.py): `triage/rules/runbooks.py`

### Answers and reports

- [Incident report](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/report.py): `triage/report.py`
- [Question router](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/router.py): `triage/answer/router.py`
- [Verified fact bundle](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/bundle.py): `triage/answer/bundle.py`
- [Answer pipeline](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/pipeline.py): `triage/answer/pipeline.py`
- [Prompt anonymizer](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/anonymize.py): `triage/answer/anonymize.py`
- [Answer validator](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/validate.py): `triage/answer/validate.py`
- [Template fallback](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/answer/templates.py): `triage/answer/templates.py`

### Serving and clients

- [HTTP API](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/api.py): `triage/api.py`
- [Web interface](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/web/app.js): `web/app.js`
- [Batch questions](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/batch.py): `triage/batch.py`

### LLM wording

- [LLM provider pool](https://github.com/m-ali1122/security-incident-triage-assistant/blob/main/triage/llm/pool.py): `triage/llm/pool.py`

### Other components

- **Analyst**
- **Incident data pack**
- **LLM providers**

## Connections

- Analyst → Web interface: asks questions (evidence: `README.md`)
- Web interface → HTTP API: sends requests (evidence: `README.md`)
- Incident data pack → Table loaders: loads tables (evidence: `README.md`)
- Incident data pack → Log parser: parses logs (evidence: `README.md`)
- Table loaders → Coverage model: provides coverage data (evidence: `triage/parsers/coverage.py`)
- Runtime configuration → Fact store: configures paths (evidence: `triage/facts.py`)
- Fact store → Log parser: parses events (evidence: `triage/facts.py`)
- Fact store → Table loaders: loads tables (evidence: `triage/facts.py`)
- Fact store → Rule engine: builds findings (evidence: `triage/facts.py`)
- Log parser → Evidence contracts: creates events (evidence: `triage/parsers/logs.py`)
- Table loaders → Evidence contracts: creates typed records (evidence: `triage/parsers/tables.py`)
- Fact store → Evidence graph: builds graph (evidence: `triage/facts.py`)
- Rule engine → Rule detectors: runs checks (evidence: `triage/rules/engine.py`)
- Rule engine → Incident clustering: clusters findings (evidence: `triage/rules/engine.py`)
- Rule engine → Severity scoring: scores incidents (evidence: `triage/rules/engine.py`)
- Rule engine → Escalation contacts: selects contacts (evidence: `triage/rules/engine.py`)
- Rule engine → Runbook actions: selects actions (evidence: `triage/rules/engine.py`)
- Rule detectors → Change calendar checks: checks changes (evidence: `triage/rules/detectors.py`)
- HTTP API → Fact store: serves facts (evidence: `triage/api.py`)
- HTTP API → Answer pipeline: answers questions (evidence: `triage/api.py`)
- HTTP API → Incident report: serves report (evidence: `triage/api.py`)
- Batch questions → Fact store: loads facts (evidence: `triage/batch.py`)
- Batch questions → Answer pipeline: answers questions (evidence: `triage/batch.py`)
- Answer pipeline → Question router: routes question (evidence: `triage/answer/pipeline.py`)
- Answer pipeline → Verified fact bundle: builds fact bundle (evidence: `triage/answer/pipeline.py`)
- Answer pipeline → Prompt anonymizer: anonymizes prompt (evidence: `triage/answer/pipeline.py`)
- Answer pipeline → LLM provider pool: requests wording (evidence: `triage/answer/pipeline.py`)
- Answer pipeline → Answer validator: validates answer (evidence: `triage/answer/pipeline.py`)
- Answer pipeline → Template fallback: falls back (evidence: `triage/answer/pipeline.py`)
- LLM provider pool → LLM providers: calls providers (evidence: `triage/llm/pool.py`)
- Answer pipeline → Fact store: reads verified facts (evidence: `triage/answer/pipeline.py`)