How nithishsgowda/ai-security-copilot works
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: result_parser.py Normalize · language_detector.py Language detect · main.py CLI · app.py Dashboard
Components 21
Entry points
Target acquisition
- Repo cloner · Resolves local paths or GitHub sources into a workspace.
utils/repo_cloner.py - Language detect · Selects applicable scanners based on repository language.
utils/language_detector.py
Scanning layer
- Bandit · Python-focused security analysis.
scanner/bandit_scan.py - Semgrep · Rule-based code pattern and vulnerability checks.
scanner/semgrep_scan.py - Trivy · Container and dependency exposure scanning.
scanner/trivy_scan.py - GoSec · Go-specific security checks.
scanner/gosec_scanner.py - Brakeman · Ruby on Rails security scanning.
scanner/brakeman_scanner.py - PHP scan · PHP-specific vulnerability checks.
scanner/php_scanner.py - Secrets scan · Detects credentials, keys, and leaked secrets.
scanner/secrets_scanner.py - AI review · Scanner-backed code review using AI assistance.
scanner/ai_code_reviewer.py
Normalization and scoring
- Normalize · Converts tool outputs into a shared finding schema.
parser/result_parser.py - Risk score · Aggregates findings into risk score and tier.
risk_engine/risk_calculator.py
AI services
- AI gateway · Routes requests across local and cloud model providers.
ai_engine/unified_client.py - Explain · Turns findings into plain-language explanations.
ai_engine/vulnerability_explainer.py - Patch gen · Produces remediation suggestions and secure code variants.
ai_engine/patch_generator.py
Presentation and export
- PDF report · Generates shareable report output.
utils/pdf_report.py - Auto fixer · Applies generated fixes back to code.
utils/auto_fixer.py
Connections 36
- 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