# nithishsgowda/ai-security-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/nithishsgowda/ai-security-copilot
- Repository: https://github.com/nithishsgowda/ai-security-copilot

## Overview

1. This repository is a local security-analysis pipeline with two user-facing entry points: a CLI in `main.py` and a Streamlit dashboard in `dashboard/app.py`. Both orchestrate the same backend flow: acquire source code, run scanners, normalize findings, score risk, optionally call AI, and render/export results.

2. The first boundary is target acquisition. `utils/repo_cloner.py` supports scanning either a local path or a GitHub repository URL by cloning it into a workspace. That keeps “source selection” separate from the scanning and analysis stages.

3. The scanning layer lives in `scanner/` and is the main fan-out point. It wraps multiple security tools and specialized checks: `bandit_scan.py`, `semgrep_scan.py`, `trivy_scan.py`, plus language-specific scanners for Go (`gosec_scanner.py`), Ruby/Rails (`brakeman_scanner.py`), PHP (`php_scanner.py`), secrets detection (`secrets_scanner.py`), and AI-assisted review (`ai_code_reviewer.py`).

4. The scanner subsystem is deliberately heterogeneous: some scanners focus on source-code patterns, some on dependency/CVE exposure, and some on secrets or higher-level code quality concerns. The repository’s architecture is therefore “multi-scanner, multi-signal,” rather than a single static-analysis engine.

5. Scanner outputs converge in `parser/result_parser.py`, which is the normalization boundary. It converts tool-specific JSON or text outputs into one shared finding shape containing file, line, severity, tool, description, and code context. This makes downstream scoring, display, and AI prompting tool-agnostic.

6. Risk assessment is separated into `risk_engine/risk_calculator.py`. It aggregates normalized findings into an overall project security score and risk tier. In diagram terms, this is the scoring stage between raw findings and human-readable reporting.

7. AI capabilities are isolated in `ai_engine/`. The `unified_client.py` abstracts multiple backends, while provider-specific clients support Ollama, LM Studio, LocalAI, OpenAI, Groq, Google, and Cloudflare. On top of that, `vulnerability_explainer.py` generates plain-language explanations and `patch_generator.py` produces remediation suggestions or secure code variants.

8. The AI layer is not hard-wired to one runtime. The README emphasizes local-first operation, but the code structure shows a backend-agnostic interface that can route to local models or cloud services depending on configuration. That makes the AI subsystem a pluggable integration boundary rather than a fixed dependency.

9. Output and user experience are split across two channels. The dashboard in `dashboard/` provides interactive visualization, filtering, and on-demand AI analysis, while CLI execution is intended for scripted scans and file-based outputs. `utils/pdf_report.py` and the documented JSON/CSV exports indicate reporting is a separate post-processing concern.

10. Supporting utilities in `utils/` handle cross-cutting concerns: `language_detector.py` helps choose applicable scanners, `auto_fixer.py` applies generated fixes, and `helpers.py` likely centralizes shared formatting or file operations. These are helper boundaries that support orchestration rather than owning analysis logic.

11. Configuration and environment setup are part of the operational boundary. `config.ini`, the `config/` package, `.streamlit/config.toml`, platform setup scripts, and `requirements.txt` define how the tool runs locally. The project is designed to be executed on the developer’s machine with scanners and AI services available locally or via configured APIs.

12. CI/CD integration appears through `.github/workflows/security-scan.yml`, which suggests the same scanning pipeline can be run in automation. So the architecture supports both interactive/local use and repository-level automated security checks.

13. For an architecture diagram, the most important data flow is: target code/repo → scanner fan-out → normalized findings → risk scoring → optional AI enrichment/fix generation → dashboard/CLI/report export. The key subsystem boundaries are acquisition, scanning, normalization, scoring, AI backend abstraction, and presentation/export.

Main entry points: [`parser/result_parser.py`](https://github.com/nithishsgowda/ai-security-copilot/blob/main/parser/result_parser.py) (Normalize), [`utils/language_detector.py`](https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/language_detector.py) (Language detect), [`main.py`](https://github.com/nithishsgowda/ai-security-copilot/blob/main/main.py) (CLI), [`dashboard/app.py`](https://github.com/nithishsgowda/ai-security-copilot/blob/main/dashboard/app.py) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main_py["CLI<br/>entrypoint<br/>[main.py]"]
  node_dashboard_app_py["Dashboard<br/>entrypoint<br/>[app.py]"]
end

subgraph group_acquisition["Target acquisition"]
  node_repo_cloner["Repo cloner<br/>acquisition<br/>[repo_cloner.py]"]
  node_language_detector["Language detect<br/>helper"]
end

subgraph group_scanning["Scanning layer"]
  node_bandit_scan["Bandit<br/>source scanner<br/>[bandit_scan.py]"]
  node_semgrep_scan["Semgrep<br/>pattern scanner<br/>[semgrep_scan.py]"]
  node_trivy_scan["Trivy<br/>dependency scanner<br/>[trivy_scan.py]"]
  node_gosec_scanner["GoSec<br/>language scanner<br/>[gosec_scanner.py]"]
  node_brakeman_scanner["Brakeman<br/>language scanner"]
  node_php_scanner["PHP scan<br/>language scanner<br/>[php_scanner.py]"]
  node_secrets_scanner["Secrets scan<br/>[secrets_scanner.py]"]
  node_ai_code_reviewer["AI review<br/>ai-assisted scanner"]
end

subgraph group_analysis["Normalization and scoring"]
  node_result_parser["Normalize<br/>parser<br/>[result_parser.py]"]
  node_risk_calculator["Risk score<br/>scoring engine<br/>[risk_calculator.py]"]
end

subgraph group_ai["AI services"]
  node_unified_client["AI gateway<br/>ai backend<br/>[unified_client.py]"]
  node_vulnerability_explainer["Explain<br/>ai output"]
  node_patch_generator["Patch gen<br/>ai output<br/>[patch_generator.py]"]
end

subgraph group_output["Presentation and export"]
  node_pdf_report["PDF report<br/>exporter<br/>[pdf_report.py]"]
  node_auto_fixer["Auto fixer<br/>remediation<br/>[auto_fixer.py]"]
end

subgraph group_ops["Config and automation"]
  node_security_scan_workflow["CI scan<br/>automation<br/>[security-scan.yml]"]
  node_config_ini["Config<br/>[config.ini]"]
end

node_main_py -->|"acquire target"| node_repo_cloner
node_dashboard_app_py -->|"acquire target"| node_repo_cloner
node_main_py -->|"detect languages"| node_language_detector
node_dashboard_app_py -->|"detect languages"| node_language_detector
node_language_detector -->|"select"| node_bandit_scan
node_language_detector -->|"select"| node_semgrep_scan
node_language_detector -->|"select"| node_trivy_scan
node_language_detector -->|"select"| node_gosec_scanner
node_language_detector -->|"select"| node_brakeman_scanner
node_language_detector -->|"select"| node_php_scanner
node_main_py -->|"run"| node_secrets_scanner
node_dashboard_app_py -->|"run"| node_secrets_scanner
node_main_py -->|"run"| node_ai_code_reviewer
node_dashboard_app_py -->|"run"| node_ai_code_reviewer
node_bandit_scan -->|"normalize"| node_result_parser
node_semgrep_scan -->|"normalize"| node_result_parser
node_trivy_scan -->|"normalize"| node_result_parser
node_gosec_scanner -->|"normalize"| node_result_parser
node_brakeman_scanner -->|"normalize"| node_result_parser
node_php_scanner -->|"normalize"| node_result_parser
node_secrets_scanner -->|"normalize"| node_result_parser
node_ai_code_reviewer -->|"model call"| node_unified_client
node_result_parser -->|"score"| node_risk_calculator
node_result_parser -->|"context for AI"| node_vulnerability_explainer
node_result_parser -->|"context for fix"| node_patch_generator
node_risk_calculator -->|"report"| node_main_py
node_risk_calculator -->|"visualize"| node_dashboard_app_py
node_vulnerability_explainer -->|"enrich UI"| node_dashboard_app_py
node_patch_generator -->|"apply"| node_auto_fixer
node_main_py -->|"export"| node_pdf_report
node_dashboard_app_py -->|"export"| node_pdf_report
node_security_scan_workflow -->|"automate"| node_main_py
node_config_ini -->|"configure"| node_main_py
node_config_ini -->|"configure"| node_dashboard_app_py
node_config_ini -->|"provider settings"| node_unified_client
node_config_ini -->|"env"| node_security_scan_workflow

click node_main_py "https://github.com/nithishsgowda/ai-security-copilot/blob/main/main.py"
click node_dashboard_app_py "https://github.com/nithishsgowda/ai-security-copilot/blob/main/dashboard/app.py"
click node_repo_cloner "https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/repo_cloner.py"
click node_language_detector "https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/language_detector.py"
click node_bandit_scan "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/bandit_scan.py"
click node_semgrep_scan "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/semgrep_scan.py"
click node_trivy_scan "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/trivy_scan.py"
click node_gosec_scanner "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/gosec_scanner.py"
click node_brakeman_scanner "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/brakeman_scanner.py"
click node_php_scanner "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/php_scanner.py"
click node_secrets_scanner "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/secrets_scanner.py"
click node_ai_code_reviewer "https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/ai_code_reviewer.py"
click node_result_parser "https://github.com/nithishsgowda/ai-security-copilot/blob/main/parser/result_parser.py"
click node_risk_calculator "https://github.com/nithishsgowda/ai-security-copilot/blob/main/risk_engine/risk_calculator.py"
click node_unified_client "https://github.com/nithishsgowda/ai-security-copilot/blob/main/ai_engine/unified_client.py"
click node_vulnerability_explainer "https://github.com/nithishsgowda/ai-security-copilot/blob/main/ai_engine/vulnerability_explainer.py"
click node_patch_generator "https://github.com/nithishsgowda/ai-security-copilot/blob/main/ai_engine/patch_generator.py"
click node_pdf_report "https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/pdf_report.py"
click node_auto_fixer "https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/auto_fixer.py"
click node_security_scan_workflow "https://github.com/nithishsgowda/ai-security-copilot/blob/main/.github/workflows/security-scan.yml"
click node_config_ini "https://github.com/nithishsgowda/ai-security-copilot/blob/main/config.ini"

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_main_py,node_dashboard_app_py,node_security_scan_workflow,node_config_ini toneBlue
class node_repo_cloner,node_language_detector toneAmber
class node_bandit_scan,node_semgrep_scan,node_trivy_scan,node_gosec_scanner,node_brakeman_scanner,node_php_scanner,node_secrets_scanner,node_ai_code_reviewer toneMint
class node_result_parser,node_risk_calculator toneRose
class node_unified_client,node_vulnerability_explainer,node_patch_generator toneIndigo
class node_pdf_report,node_auto_fixer toneTeal
```

## Components

### Entry points

- [CLI](https://github.com/nithishsgowda/ai-security-copilot/blob/main/main.py): entrypoint · Command-line orchestrator for local scans and reports. · `main.py`
- [Dashboard](https://github.com/nithishsgowda/ai-security-copilot/blob/main/dashboard/app.py): entrypoint · Streamlit UI for interactive scanning and review. · `dashboard/app.py`

### Target acquisition

- [Repo cloner](https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/repo_cloner.py): acquisition · Resolves local paths or GitHub sources into a workspace. · `utils/repo_cloner.py`
- [Language detect](https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/language_detector.py): helper · Selects applicable scanners based on repository language. · `utils/language_detector.py`

### Scanning layer

- [Bandit](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/bandit_scan.py): source scanner · Python-focused security analysis. · `scanner/bandit_scan.py`
- [Semgrep](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/semgrep_scan.py): pattern scanner · Rule-based code pattern and vulnerability checks. · `scanner/semgrep_scan.py`
- [Trivy](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/trivy_scan.py): dependency scanner · Container and dependency exposure scanning. · `scanner/trivy_scan.py`
- [GoSec](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/gosec_scanner.py): language scanner · Go-specific security checks. · `scanner/gosec_scanner.py`
- [Brakeman](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/brakeman_scanner.py): language scanner · Ruby on Rails security scanning. · `scanner/brakeman_scanner.py`
- [PHP scan](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/php_scanner.py): language scanner · PHP-specific vulnerability checks. · `scanner/php_scanner.py`
- [Secrets scan](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/secrets_scanner.py): secrets scanner · Detects credentials, keys, and leaked secrets. · `scanner/secrets_scanner.py`
- [AI review](https://github.com/nithishsgowda/ai-security-copilot/blob/main/scanner/ai_code_reviewer.py): ai-assisted scanner · Scanner-backed code review using AI assistance. · `scanner/ai_code_reviewer.py`

### Normalization and scoring

- [Normalize](https://github.com/nithishsgowda/ai-security-copilot/blob/main/parser/result_parser.py): parser · Converts tool outputs into a shared finding schema. · `parser/result_parser.py`
- [Risk score](https://github.com/nithishsgowda/ai-security-copilot/blob/main/risk_engine/risk_calculator.py): scoring engine · Aggregates findings into risk score and tier. · `risk_engine/risk_calculator.py`

### AI services

- [AI gateway](https://github.com/nithishsgowda/ai-security-copilot/blob/main/ai_engine/unified_client.py): ai backend · Routes requests across local and cloud model providers. · `ai_engine/unified_client.py`
- [Explain](https://github.com/nithishsgowda/ai-security-copilot/blob/main/ai_engine/vulnerability_explainer.py): ai output · Turns findings into plain-language explanations. · `ai_engine/vulnerability_explainer.py`
- [Patch gen](https://github.com/nithishsgowda/ai-security-copilot/blob/main/ai_engine/patch_generator.py): ai output · Produces remediation suggestions and secure code variants. · `ai_engine/patch_generator.py`

### Presentation and export

- [PDF report](https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/pdf_report.py): exporter · Generates shareable report output. · `utils/pdf_report.py`
- [Auto fixer](https://github.com/nithishsgowda/ai-security-copilot/blob/main/utils/auto_fixer.py): remediation · Applies generated fixes back to code. · `utils/auto_fixer.py`

### Config and automation

- [CI scan](https://github.com/nithishsgowda/ai-security-copilot/blob/main/.github/workflows/security-scan.yml): automation · GitHub Actions workflow for automated security scanning. · `.github/workflows/security-scan.yml`
- [Config](https://github.com/nithishsgowda/ai-security-copilot/blob/main/config.ini): runtime config · Local configuration and environment settings. · `config.ini`

## Connections

- CLI → Repo cloner: acquire target
- Dashboard → Repo cloner: acquire target
- CLI → Language detect: detect languages
- Dashboard → Language detect: detect languages
- Language detect → Bandit: select
- Language detect → Semgrep: select
- Language detect → Trivy: select
- Language detect → GoSec: select
- Language detect → Brakeman: select
- Language detect → PHP scan: select
- CLI → Secrets scan: run
- Dashboard → Secrets scan: run
- CLI → AI review: run
- Dashboard → AI review: run
- Bandit → Normalize: normalize
- Semgrep → Normalize: normalize
- Trivy → Normalize: normalize
- GoSec → Normalize: normalize
- Brakeman → Normalize: normalize
- PHP scan → Normalize: normalize
- Secrets scan → Normalize: normalize
- AI review → AI gateway: model call
- Normalize → Risk score: score
- Normalize → Explain: context for AI
- Normalize → Patch gen: context for fix
- Risk score → CLI: report
- Risk score → Dashboard: visualize
- Explain → Dashboard: enrich UI
- Patch gen → Auto fixer: apply
- CLI → PDF report: export
- Dashboard → PDF report: export
- CI scan → CLI: automate
- Config → CLI: configure
- Config → Dashboard: configure
- Config → AI gateway: provider settings
- Config → CI scan: env
