devsecops-radar 0.1.9__tar.gz → 0.2.0__tar.gz

devsecops_radar-0.2.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: devsecops-radar
+Version: 0.2.0
+Summary: Unified CI/CD Security Dashboard — Pipeline Sentinel
+Author-email: Mehrdoost <70381337+Mehrdoost@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Mehrdoost/devsecops-radar
+Project-URL: Source, https://github.com/Mehrdoost/devsecops-radar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=3.0
+Requires-Dist: semgrep>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# 🛡️ Pipeline Sentinel
+
+**Unified CI/CD Security Observability — Offline‑Ready, AI‑Enhanced, Extensible**
+
+Pipeline Sentinel is an open‑source DevSecOps command center. It **aggregates, correlates, and visualises** security findings from **Trivy, Semgrep, Poutine, Zizmor** and any custom scanner you plug in. It works **fully offline**, can optionally pull **community‑curated rules**, and now includes:
+
+- 🧠 **LLM‑powered analysis** (Ollama & LiteLLM) with auto‑remediation
+- 🕸️ **Deep attack‑path visualisation** with MITRE ATT&CK mapping
+- 📊 **Compliance reports** (PDF) aligned to CIS, PCI‑DSS, ISO 27001
+- 🛡️ **Policy‑as‑Code** engine to enforce security gates
+- 🐳 **Production‑ready Docker** (multi‑stage, non‑root)
+
+[![GitHub stars](https://img.shields.io/github/stars/Mehrdoost/devsecops-radar?style=social)](https://github.com/Mehrdoost/devsecops-radar/stargazers)
+[![License](https://img.shields.io/github/license/Mehrdoost/devsecops-radar)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/devsecops-radar.svg)](https://pypi.org/project/devsecops-radar/)
+[![GitHub release](https://img.shields.io/github/v/release/Mehrdoost/devsecops-radar?include_prereleases)](https://github.com/Mehrdoost/devsecops-radar/releases)
+[![CI](https://github.com/Mehrdoost/devsecops-radar/actions/workflows/test-action.yml/badge.svg)](https://github.com/Mehrdoost/devsecops-radar/actions/workflows/test-action.yml)
+
+> 📖 **Read this in:** [Русский](README_ru.md) | [中文](README_zh.md)
+
+---
+
+## 📸 Dashboard Preview
+
+![Pipeline Sentinel Dashboard](docs/Demo.gif)
+*(Severity doughnut, trend line chart, attack‑path graph, topology view, executive summary — all fully offline.)*
+
+---
+
+## 🚀 Quick Start (3 Commands)
+
+```bash
+pip install devsecops-radar
+devsecops-radar --trivy sample_trivy.json --semgrep sample_semgrep.json
+devsecops-radar-web
+```
+
+Open http://localhost:8080 – your unified dashboard is live with sample data.
+
+---
+
+## 📖 What Is Pipeline Sentinel?
+
+Pipeline Sentinel is a security observability platform for CI/CD pipelines.
+It takes the fragmented JSON output from popular open‑source scanners — Trivy (containers & dependencies), Semgrep (static code analysis), Poutine (GitLab CI security), and Zizmor (GitHub Actions security) — and merges them into a single, dark‑mode dashboard.
+
+### Why It Matters
+In 2026, the DevSecOps community witnessed multiple supply‑chain attacks (CVE‑2026‑33634, Mini Shai‑Hulud, TeamPCP) that compromised scanner tools and CI/CD pipelines themselves.
+Scanning your code is no longer enough — **you must also scan your pipeline**.
+Pipeline Sentinel unifies container scanning, static analysis, and pipeline security checks under one roof, giving you full visibility.
+
+### Who Should Use It
+
+| Persona | Benefit |
+| :--- | :--- |
+| **DevSecOps Engineers** | One dashboard for Trivy, Semgrep, Poutine, and Zizmor. Correlate findings, track trends, and enforce policies. |
+| **Penetration Testers** | Feed custom tool JSON, generate AI‑powered attack graphs with MITRE ATT&CK mapping, and create professional reports. |
+| **Security Teams (air‑gapped)** | Works 100% offline. No CDN, no external API calls. All assets embedded. |
+| **Compliance Officers** | Generate PDF reports aligned to CIS, PCI‑DSS, or ISO 27001. |
+| **CI/CD Pipeline Owners** | Integrate via GitHub Action to get a security summary on every PR. |
+
+---
+
+## ✨ What's New in v0.3.0
+
+| Capability | Description |
+| :--- | :--- |
+| 🧠 **Auto‑Remediation (`--fix`)** | AI‑suggested fixes applied automatically; creates a git branch for review. |
+| 🕸️ **Deep Attack‑Path Visualisation** | Topology‑aware attack graphs with MITRE ATT&CK tactics/techniques. |
+| 📊 **Compliance Reports** | PDF reports mapped to CIS, PCI‑DSS, and ISO 27001 controls. |
+| 🛡️ **Policy‑as‑Code (`--policy`)** | Enforce rules like “fail if CRITICAL > 5”. |
+| 🔒 **Input Validation** | All scanner targets are sanitised against command injection. |
+| 🪵 **Structured Logging** | Loguru for clear, coloured, and timestamped logs. |
+| 🔐 **API Key Protection** | Simple API key authentication for the web dashboard. |
+| 🐳 **Improved Docker Image** | Multi‑stage build, non‑root user, smaller size. |
+
+---
+
+## 📦 Installation
+
+### Option 1 – PyPI (Recommended)
+```bash
+pip install devsecops-radar
+```
+
+### Option 2 – From Source
+```bash
+git clone [https://github.com/Mehrdoost/devsecops-radar.git](https://github.com/Mehrdoost/devsecops-radar.git)
+cd devsecops-radar
+pip install -e .
+```
+
+### Option 3 – Docker
+```bash
+docker pull ghcr.io/mehrdoost/devsecops-radar:latest
+docker run -p 8080:8080 ghcr.io/mehrdoost/devsecops-radar:latest
+```
+
+**With a custom findings file:**
+```bash
+docker run -p 8080:8080 -v $(pwd)/findings.json:/data/findings.json ghcr.io/mehrdoost/devsecops-radar:latest
+```
+
+---
+
+## 📋 Complete Command Reference
+
+### `devsecops-radar` – CLI Flags
+
+| Flag | Description | Example |
+| :--- | :--- | :--- |
+| `--trivy` | Trivy JSON file or image name | `--trivy results.json` or `--trivy nginx:latest` |
+| `--semgrep` | Semgrep JSON file or directory | `--semgrep results.json` or `--semgrep ./src` |
+| `--poutine` | Poutine JSON file or repository path | `--poutine results.json` or `--poutine ./repo` |
+| `--zizmor` | Zizmor JSON file or repository path | `--zizmor results.json` or `--zizmor ./repo` |
+| `--rules` | Directory with custom JSON rule files | `--rules ~/my-security-rules/` |
+| `--policy` | Policy JSON file for gating | `--policy policy.json` |
+| `--analyze` | Enable LLM analysis (Ollama required) | `--analyze` |
+| `--llm-backend` | `ollama` (default) or `litellm` | `--llm-backend litellm` |
+| `--llm-model` | Model name | `--llm-model gpt-4o-mini` |
+| `--fix` | Auto‑apply AI‑suggested fixes and create a git branch | `--fix` |
+| `--topology` | Path to topology JSON file | `--topology topology.json` |
+| `--compliance` | Compliance framework: `CIS`, `PCI-DSS`, `ISO27001` | `--compliance CIS` |
+| `--report` | Generate PDF report (output filename) | `--report security_report.pdf` |
+| `--output` | Output JSON file (default: findings.json) | `--output merged.json` |
+
+### `devsecops-radar-web` – Web Server
+
+```bash
+devsecops-radar-web                        # http://localhost:8080
+FINDINGS_FILE=my.json devsecops-radar-web  # custom findings file
+PIPELINE_API_KEY=secret devsecops-radar-web  # enable API authentication
+```
+
+---
+
+## 🧭 How to Use Pipeline Sentinel – Step by Step
+
+### 1. Run Your Security Scanners
+Generate JSON output from your tools:
+
+```bash
+trivy image --format json -o trivy.json nginx:latest
+semgrep --config=auto --json --output semgrep.json .
+poutine scan ./repo --format json --output poutine.json
+zizmor scan ./repo --output zizmor.json --format json
+```
+
+### 2. Merge Findings with the CLI
+
+```bash
+devsecops-radar --trivy trivy.json --semgrep semgrep.json --poutine poutine.json --zizmor zizmor.json
+```
+
+### 3. View the Dashboard
+
+```bash
+devsecops-radar-web
+```
+Open http://localhost:8080. The dashboard shows:
+*   **Severity Breakdown** (doughnut chart)
+*   **Trend Over Time** (line chart from scan history)
+*   **Pipeline Security** (Poutine + Zizmor statistics)
+*   **Attack Path Graph** (if AI analysis enabled)
+*   **Executive Summary** (risk score, AI summary)
+*   **Findings Table** (searchable & filterable)
+
+### 4. Enable AI Analysis (Optional)
+
+```bash
+ollama pull llama3.2:latest
+devsecops-radar --trivy trivy.json --analyze
+devsecops-radar-web
+```
+The LLM generates `findings_ai_summary.json` containing:
+*   `executive_summary`, `risk_score`
+*   `attack_paths` with MITRE ATT&CK tactics
+*   `top_remediations` (some with `fix_diff`)
+*   `false_positives_likely`
+
+*(The dashboard automatically renders the attack graph and executive summary.)*
+
+### 5. Deep Attack Visualisation with Topology
+Create a `topology.json` describing your assets and connections (see `sample_topology.json`). Then run:
+
+```bash
+devsecops-radar --trivy trivy.json --analyze --topology topology.json
+```
+The LLM will map findings onto your topology, producing attack paths that reflect lateral movement across servers and subnets.
+
+### 6. Auto‑Remediation (`--fix`)
+
+```bash
+devsecops-radar --trivy trivy.json --analyze --fix
+```
+The tool will:
+1.  Apply AI‑suggested fixes to vulnerable files.
+2.  Create a new git branch `auto-fix` and push it.
+3.  Print a message to open a Pull Request.
+
+### 7. Policy Enforcement (`--policy`)
+Create a `policy.json` file:
+
+```json
+{
+  "max_critical": 5, 
+  "on_violation": "fail"
+}
+```
+
+Run:
+```bash
+devsecops-radar --trivy trivy.json --policy policy.json
+```
+If critical findings exceed 5, the command exits with code 1 – suitable for CI/CD gates.
+
+### 8. Generate Compliance Reports (`--report`)
+
+```bash
+devsecops-radar --trivy trivy.json --analyze --compliance CIS --report cis-report.pdf
+```
+A PDF report is created with an executive summary, risk score, findings table, and compliance mapping (CIS, PCI‑DSS, or ISO 27001).
+
+---
+
+## 🔌 Offline + Online: Hybrid RuleFusion Engine
+
+Pipeline Sentinel is designed for both air‑gapped and connected environments.
+
+### Offline – Local Rules Directory
+```bash
+devsecops-radar --trivy scan.json --rules ~/my-rules/
+```
+Place any JSON file in the folder. The engine auto‑detects Trivy, Semgrep, Poutine, Zizmor, or plain‑list formats.
+
+### Online – Community Rules (Optional)
+```bash
+devsecops-radar --update-rules
+```
+Clones (or pulls) the `devsecops-radar-rules` repository to `~/.devsecops-radar/community-rules/`.
+
+---
+
+## 🏗️ Architecture
+
+```text
+devsecops_radar/
+├── cli/            # CLI entry – plugin registry, policy, remediation
+├── core/           # RuleFusion, DB, analysers, reporting
+├── scanners/       # Pluggable scanner classes (BaseScanner)
+└── web/            # Flask dashboard (embedded HTML)
+```
+
+*Adding a new scanner is as simple as extending `BaseScanner` and implementing `parse()`.*
+
+---
+
+## 🔒 Security
+
+*   **Input validation** – scanner targets are sanitised.
+*   **Offline‑first** – no data leaves your network.
+*   **LLM privacy** – Ollama runs locally; optional LiteLLM for cloud models.
+*   **API authentication** – optional API key for dashboard access.
+*   **Non‑root Docker** – container runs as unprivileged user.
+*   **Policy‑as‑Code** – enforce gates before deployment.
+
+---
+
+## 🤖 GitHub Action
+
+```yaml
+- name: Pipeline Sentinel
+  uses: Mehrdoost/devsecops-radar/action@main
+  with:
+    trivy_report: trivy-results.json
+    semgrep_report: semgrep-results.json
+    poutine_report: poutine-results.json
+    zizmor_report: zizmor-results.json
+```
+*Merges findings, creates a job summary, and outputs CRITICAL/HIGH counts.*
+
+---
+
+## 🗺️ Roadmap
+
+- [x] Multi‑scanner plugin engine
+- [x] LLM analysis (Ollama + LiteLLM) with auto‑remediation
+- [x] Scan history, trend chart, scan diff
+- [x] Attack‑path visualisation with MITRE ATT&CK & topology
+- [x] Policy‑as‑Code engine
+- [x] Compliance reports (PDF)
+- [x] GitHub Action
+- [x] Docker image (multi‑stage, non‑root)
+- [ ] Jira / Slack integration
+- [ ] SARIF & CycloneDX support
+
+---
+
+## 👨‍💻 Author
+
+**Mehrdoost**
+
+[![GitHub](https://img.shields.io/badge/GitHub-Mehrdoost-181717?logo=github)](https://github.com/Mehrdoost)
+
+
+---
+
+## 📜 License
+
+MIT – see [LICENSE](LICENSE).
+
+⭐ **If this project helps your team ship safer software, drop a star — it makes a real difference.**

devsecops_radar-0.2.0/README.md

@@ -0,0 +1,312 @@
+# 🛡️ Pipeline Sentinel
+
+**Unified CI/CD Security Observability — Offline‑Ready, AI‑Enhanced, Extensible**
+
+Pipeline Sentinel is an open‑source DevSecOps command center. It **aggregates, correlates, and visualises** security findings from **Trivy, Semgrep, Poutine, Zizmor** and any custom scanner you plug in. It works **fully offline**, can optionally pull **community‑curated rules**, and now includes:
+
+- 🧠 **LLM‑powered analysis** (Ollama & LiteLLM) with auto‑remediation
+- 🕸️ **Deep attack‑path visualisation** with MITRE ATT&CK mapping
+- 📊 **Compliance reports** (PDF) aligned to CIS, PCI‑DSS, ISO 27001
+- 🛡️ **Policy‑as‑Code** engine to enforce security gates
+- 🐳 **Production‑ready Docker** (multi‑stage, non‑root)
+
+[![GitHub stars](https://img.shields.io/github/stars/Mehrdoost/devsecops-radar?style=social)](https://github.com/Mehrdoost/devsecops-radar/stargazers)
+[![License](https://img.shields.io/github/license/Mehrdoost/devsecops-radar)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/devsecops-radar.svg)](https://pypi.org/project/devsecops-radar/)
+[![GitHub release](https://img.shields.io/github/v/release/Mehrdoost/devsecops-radar?include_prereleases)](https://github.com/Mehrdoost/devsecops-radar/releases)
+[![CI](https://github.com/Mehrdoost/devsecops-radar/actions/workflows/test-action.yml/badge.svg)](https://github.com/Mehrdoost/devsecops-radar/actions/workflows/test-action.yml)
+
+> 📖 **Read this in:** [Русский](README_ru.md) | [中文](README_zh.md)
+
+---
+
+## 📸 Dashboard Preview
+
+![Pipeline Sentinel Dashboard](docs/Demo.gif)
+*(Severity doughnut, trend line chart, attack‑path graph, topology view, executive summary — all fully offline.)*
+
+---
+
+## 🚀 Quick Start (3 Commands)
+
+```bash
+pip install devsecops-radar
+devsecops-radar --trivy sample_trivy.json --semgrep sample_semgrep.json
+devsecops-radar-web
+```
+
+Open http://localhost:8080 – your unified dashboard is live with sample data.
+
+---
+
+## 📖 What Is Pipeline Sentinel?
+
+Pipeline Sentinel is a security observability platform for CI/CD pipelines.
+It takes the fragmented JSON output from popular open‑source scanners — Trivy (containers & dependencies), Semgrep (static code analysis), Poutine (GitLab CI security), and Zizmor (GitHub Actions security) — and merges them into a single, dark‑mode dashboard.
+
+### Why It Matters
+In 2026, the DevSecOps community witnessed multiple supply‑chain attacks (CVE‑2026‑33634, Mini Shai‑Hulud, TeamPCP) that compromised scanner tools and CI/CD pipelines themselves.
+Scanning your code is no longer enough — **you must also scan your pipeline**.
+Pipeline Sentinel unifies container scanning, static analysis, and pipeline security checks under one roof, giving you full visibility.
+
+### Who Should Use It
+
+| Persona | Benefit |
+| :--- | :--- |
+| **DevSecOps Engineers** | One dashboard for Trivy, Semgrep, Poutine, and Zizmor. Correlate findings, track trends, and enforce policies. |
+| **Penetration Testers** | Feed custom tool JSON, generate AI‑powered attack graphs with MITRE ATT&CK mapping, and create professional reports. |
+| **Security Teams (air‑gapped)** | Works 100% offline. No CDN, no external API calls. All assets embedded. |
+| **Compliance Officers** | Generate PDF reports aligned to CIS, PCI‑DSS, or ISO 27001. |
+| **CI/CD Pipeline Owners** | Integrate via GitHub Action to get a security summary on every PR. |
+
+---
+
+## ✨ What's New in v0.3.0
+
+| Capability | Description |
+| :--- | :--- |
+| 🧠 **Auto‑Remediation (`--fix`)** | AI‑suggested fixes applied automatically; creates a git branch for review. |
+| 🕸️ **Deep Attack‑Path Visualisation** | Topology‑aware attack graphs with MITRE ATT&CK tactics/techniques. |
+| 📊 **Compliance Reports** | PDF reports mapped to CIS, PCI‑DSS, and ISO 27001 controls. |
+| 🛡️ **Policy‑as‑Code (`--policy`)** | Enforce rules like “fail if CRITICAL > 5”. |
+| 🔒 **Input Validation** | All scanner targets are sanitised against command injection. |
+| 🪵 **Structured Logging** | Loguru for clear, coloured, and timestamped logs. |
+| 🔐 **API Key Protection** | Simple API key authentication for the web dashboard. |
+| 🐳 **Improved Docker Image** | Multi‑stage build, non‑root user, smaller size. |
+
+---
+
+## 📦 Installation
+
+### Option 1 – PyPI (Recommended)
+```bash
+pip install devsecops-radar
+```
+
+### Option 2 – From Source
+```bash
+git clone [https://github.com/Mehrdoost/devsecops-radar.git](https://github.com/Mehrdoost/devsecops-radar.git)
+cd devsecops-radar
+pip install -e .
+```
+
+### Option 3 – Docker
+```bash
+docker pull ghcr.io/mehrdoost/devsecops-radar:latest
+docker run -p 8080:8080 ghcr.io/mehrdoost/devsecops-radar:latest
+```
+
+**With a custom findings file:**
+```bash
+docker run -p 8080:8080 -v $(pwd)/findings.json:/data/findings.json ghcr.io/mehrdoost/devsecops-radar:latest
+```
+
+---
+
+## 📋 Complete Command Reference
+
+### `devsecops-radar` – CLI Flags
+
+| Flag | Description | Example |
+| :--- | :--- | :--- |
+| `--trivy` | Trivy JSON file or image name | `--trivy results.json` or `--trivy nginx:latest` |
+| `--semgrep` | Semgrep JSON file or directory | `--semgrep results.json` or `--semgrep ./src` |
+| `--poutine` | Poutine JSON file or repository path | `--poutine results.json` or `--poutine ./repo` |
+| `--zizmor` | Zizmor JSON file or repository path | `--zizmor results.json` or `--zizmor ./repo` |
+| `--rules` | Directory with custom JSON rule files | `--rules ~/my-security-rules/` |
+| `--policy` | Policy JSON file for gating | `--policy policy.json` |
+| `--analyze` | Enable LLM analysis (Ollama required) | `--analyze` |
+| `--llm-backend` | `ollama` (default) or `litellm` | `--llm-backend litellm` |
+| `--llm-model` | Model name | `--llm-model gpt-4o-mini` |
+| `--fix` | Auto‑apply AI‑suggested fixes and create a git branch | `--fix` |
+| `--topology` | Path to topology JSON file | `--topology topology.json` |
+| `--compliance` | Compliance framework: `CIS`, `PCI-DSS`, `ISO27001` | `--compliance CIS` |
+| `--report` | Generate PDF report (output filename) | `--report security_report.pdf` |
+| `--output` | Output JSON file (default: findings.json) | `--output merged.json` |
+
+### `devsecops-radar-web` – Web Server
+
+```bash
+devsecops-radar-web                        # http://localhost:8080
+FINDINGS_FILE=my.json devsecops-radar-web  # custom findings file
+PIPELINE_API_KEY=secret devsecops-radar-web  # enable API authentication
+```
+
+---
+
+## 🧭 How to Use Pipeline Sentinel – Step by Step
+
+### 1. Run Your Security Scanners
+Generate JSON output from your tools:
+
+```bash
+trivy image --format json -o trivy.json nginx:latest
+semgrep --config=auto --json --output semgrep.json .
+poutine scan ./repo --format json --output poutine.json
+zizmor scan ./repo --output zizmor.json --format json
+```
+
+### 2. Merge Findings with the CLI
+
+```bash
+devsecops-radar --trivy trivy.json --semgrep semgrep.json --poutine poutine.json --zizmor zizmor.json
+```
+
+### 3. View the Dashboard
+
+```bash
+devsecops-radar-web
+```
+Open http://localhost:8080. The dashboard shows:
+*   **Severity Breakdown** (doughnut chart)
+*   **Trend Over Time** (line chart from scan history)
+*   **Pipeline Security** (Poutine + Zizmor statistics)
+*   **Attack Path Graph** (if AI analysis enabled)
+*   **Executive Summary** (risk score, AI summary)
+*   **Findings Table** (searchable & filterable)
+
+### 4. Enable AI Analysis (Optional)
+
+```bash
+ollama pull llama3.2:latest
+devsecops-radar --trivy trivy.json --analyze
+devsecops-radar-web
+```
+The LLM generates `findings_ai_summary.json` containing:
+*   `executive_summary`, `risk_score`
+*   `attack_paths` with MITRE ATT&CK tactics
+*   `top_remediations` (some with `fix_diff`)
+*   `false_positives_likely`
+
+*(The dashboard automatically renders the attack graph and executive summary.)*
+
+### 5. Deep Attack Visualisation with Topology
+Create a `topology.json` describing your assets and connections (see `sample_topology.json`). Then run:
+
+```bash
+devsecops-radar --trivy trivy.json --analyze --topology topology.json
+```
+The LLM will map findings onto your topology, producing attack paths that reflect lateral movement across servers and subnets.
+
+### 6. Auto‑Remediation (`--fix`)
+
+```bash
+devsecops-radar --trivy trivy.json --analyze --fix
+```
+The tool will:
+1.  Apply AI‑suggested fixes to vulnerable files.
+2.  Create a new git branch `auto-fix` and push it.
+3.  Print a message to open a Pull Request.
+
+### 7. Policy Enforcement (`--policy`)
+Create a `policy.json` file:
+
+```json
+{
+  "max_critical": 5, 
+  "on_violation": "fail"
+}
+```
+
+Run:
+```bash
+devsecops-radar --trivy trivy.json --policy policy.json
+```
+If critical findings exceed 5, the command exits with code 1 – suitable for CI/CD gates.
+
+### 8. Generate Compliance Reports (`--report`)
+
+```bash
+devsecops-radar --trivy trivy.json --analyze --compliance CIS --report cis-report.pdf
+```
+A PDF report is created with an executive summary, risk score, findings table, and compliance mapping (CIS, PCI‑DSS, or ISO 27001).
+
+---
+
+## 🔌 Offline + Online: Hybrid RuleFusion Engine
+
+Pipeline Sentinel is designed for both air‑gapped and connected environments.
+
+### Offline – Local Rules Directory
+```bash
+devsecops-radar --trivy scan.json --rules ~/my-rules/
+```
+Place any JSON file in the folder. The engine auto‑detects Trivy, Semgrep, Poutine, Zizmor, or plain‑list formats.
+
+### Online – Community Rules (Optional)
+```bash
+devsecops-radar --update-rules
+```
+Clones (or pulls) the `devsecops-radar-rules` repository to `~/.devsecops-radar/community-rules/`.
+
+---
+
+## 🏗️ Architecture
+
+```text
+devsecops_radar/
+├── cli/            # CLI entry – plugin registry, policy, remediation
+├── core/           # RuleFusion, DB, analysers, reporting
+├── scanners/       # Pluggable scanner classes (BaseScanner)
+└── web/            # Flask dashboard (embedded HTML)
+```
+
+*Adding a new scanner is as simple as extending `BaseScanner` and implementing `parse()`.*
+
+---
+
+## 🔒 Security
+
+*   **Input validation** – scanner targets are sanitised.
+*   **Offline‑first** – no data leaves your network.
+*   **LLM privacy** – Ollama runs locally; optional LiteLLM for cloud models.
+*   **API authentication** – optional API key for dashboard access.
+*   **Non‑root Docker** – container runs as unprivileged user.
+*   **Policy‑as‑Code** – enforce gates before deployment.
+
+---
+
+## 🤖 GitHub Action
+
+```yaml
+- name: Pipeline Sentinel
+  uses: Mehrdoost/devsecops-radar/action@main
+  with:
+    trivy_report: trivy-results.json
+    semgrep_report: semgrep-results.json
+    poutine_report: poutine-results.json
+    zizmor_report: zizmor-results.json
+```
+*Merges findings, creates a job summary, and outputs CRITICAL/HIGH counts.*
+
+---
+
+## 🗺️ Roadmap
+
+- [x] Multi‑scanner plugin engine
+- [x] LLM analysis (Ollama + LiteLLM) with auto‑remediation
+- [x] Scan history, trend chart, scan diff
+- [x] Attack‑path visualisation with MITRE ATT&CK & topology
+- [x] Policy‑as‑Code engine
+- [x] Compliance reports (PDF)
+- [x] GitHub Action
+- [x] Docker image (multi‑stage, non‑root)
+- [ ] Jira / Slack integration
+- [ ] SARIF & CycloneDX support
+
+---
+
+## 👨‍💻 Author
+
+**Mehrdoost**
+
+[![GitHub](https://img.shields.io/badge/GitHub-Mehrdoost-181717?logo=github)](https://github.com/Mehrdoost)
+
+
+---
+
+## 📜 License
+
+MIT – see [LICENSE](LICENSE).
+
+⭐ **If this project helps your team ship safer software, drop a star — it makes a real difference.**