alexbarsan/AIStaticSecurityAnalyzer

# AI Static Security Analyzer AI Static Security Analyzer is a modular C#/.NET dissertation project for static application security testing (SAST). It analyzes C# source code with Roslyn, enriches findings with CWE/CVE/CVSS data, scores findings with ML.NET, exports JSON and SARIF, and can act as a CI/CD security gate. ## Current Status The repository already contains a working vertical slice: - `Analyzer.CLI` orchestrates scans, NVD sync, AI training, JSON export, and SARIF export. - `Analyzer.CLI` also exposes a repeatable fixed-corpus evaluation mode for precision/recall reporting. - `Analyzer.Roslyn` contains seven implemented rules: - weak hashing (`CWE-327`) - hardcoded secrets (`CWE-798`) - SQL injection (`CWE-89`) - command injection (`CWE-78`) - path traversal (`CWE-22`) - insecure deserialization (`CWE-502`) - unsafe XML parser configuration (`CWE-611`) - `Analyzer.CVE` stores NVD data in SQLite and enriches findings by CWE. - `Analyzer.AI` trains and loads an ML.NET model for confidence scoring, with shared feature extraction and training metadata, including deterministic split metadata, an evaluation summary, an optional model version tag, and a repeatable fixed-corpus evaluation mode for precision/recall reporting. - `Analyzer.Reporting` writes JSON, SARIF, and CSV training exports with stable fingerprints. - `.github/workflows/code-scanning.yaml` uploads SARIF to GitHub Code Scanning. - `Analyzer.Tests` now covers fixture-backed regressions for the implemented rules, reporting snapshots, scan-input behavior, command-injection coverage, path-traversal coverage, insecure-deserialization coverage, unsafe-XML coverage, configuration regression slices, fingerprint stability, and AI feature/metadata regressions. The codebase is usable, but it is still in a prototype stage. The most important next step is not only "more rules"; it is to harden the scan engine, tests, configuration, and reporting so later rules are reliable and thesis-grade. ## Architecture - `Analyzer.CLI` - Console entry point and command orchestration - `Analyzer.Core` - Domain models and core interfaces - `Analyzer.Roslyn` - Roslyn-based analysis engine and security rules - `Analyzer.CVE` - NVD API client, SQLite storage, finding enrichment - `Analyzer.AI` - ML.NET training and inference - `Analyzer.Reporting` - JSON, SARIF, and CSV export - `Analyzer.Tests` - focused regression test runner for CSV workflow, scan-input behavior, and fixture-backed rule coverage - `TempForTests` - Ad-hoc sample input, not a real automated test project ## Confirmed Repository Reality This README reflects the current repository, not only the older context notes: - The projects currently target `net9.0`. - There is now a small automated test runner, and it includes fixture-backed rule coverage for the implemented rules, reporting snapshots, CLI integration coverage, CVE enrichment coverage, and AI training round-trip coverage. - The scan engine now accepts directory, `.csproj`, and `.sln` paths with deterministic source-file ordering. - `.csproj` scanning now follows basic `ProjectReference` graphs and avoids cyclic duplication. - project scan scope is now derived from evaluated MSBuild `Compile` and `ProjectReference` items rather than only raw project XML parsing. - basic analyzer configuration now supports rule disablement, path exclusions, finding suppressions, and baseline mode through `--config` and `--baseline`. - JSON and SARIF reports now expose stable finding fingerprints for suppressions and baselines. - The CLI now prints the same final finding set that it exports after AI/filter processing. - The test harness now includes fixture-backed rule regressions, JSON/SARIF snapshot checks, CLI integration coverage for usage and exit codes, CVE enrichment tests, and a valid AI training round-trip test. - Rule registration is hardcoded inside `RoslynCodeAnalyzer`. - CLI argument parsing is custom and centralized in `Program.cs`. - The current scan engine is path-aware, but it still does not load projects through MSBuild workspace semantics. ## Recommended Priority The proposed implementation order is documented in: - [Project Context](docs/CODEX_CONTEXT_V2.md) - [User Manual](docs/USER_MANUAL.md) - [Feature 01](docs/features/01-project-aware-scan-engine.md) through [Feature 10](docs/features/10-ai-dataset-and-confidence-pipeline-v2.md) The short version: 1. Make scanning project-aware and deterministic. 2. Add automated tests and rule fixtures. 3. SQL injection with basic taint tracking is implemented. 4. Command injection with basic taint tracking is implemented. 5. Path traversal with basic taint tracking is implemented. 6. AI dataset and confidence pipeline v2 are next. ## Development Rule All feature work should start with failing automated tests whenever the behavior can be exercised locally. This is now the expected workflow for the project: 1. add or expand tests for the target behavior 2. make the implementation pass 3. update the docs/context files if the change affects future work For dissertation traceability, each meaningful feature slice should also add a short academic log under `docs/academic_logs/`. ## Prerequisites - Windows with Visual Studio 2022 or the .NET SDK - Current repository target: `.NET 9 SDK` - Optional: `NVD_API_KEY` for better NVD API rate limits If you want a more stable dissertation baseline, moving the solution to `.NET 8 LTS` is a valid next change. Right now the code and package references are aligned with `.NET 9`. ## Quick Start ### Command Overview | Usage | Short description | |---|---| | `dotnet run --project Analyzer.CLI -- ` | Scan a directory, `.csproj`, or `.sln` and print findings. | | `--json` | Write `analysis-report.json`. | | `--sarif ` | Write SARIF output for code scanning tools. | | `--ai` | Apply ML.NET confidence scoring. | | `--min-confidence <0..1>` | Filter out low-confidence findings. | | `--fail-on ` | Fail the run at a chosen severity threshold. | | `--config [file]` | Load analyzer configuration from `analyzer.json` or a custom file. | | `sync-nvd --days ` | Refresh the local NVD cache. | | `train-ai [--model-version ]` | Train the model from labeled CSV data and tag the metadata with a model version. | | `evaluate-corpus [path]` | Evaluate the analyzer against the fixed sample corpus and print rule-only precision/recall/F1. | | `compare-corpus [path] [--min-confidence <0..1>]` | Compare rule-only results against AI-confidence filtering on the fixed corpus. | | `--export-training [file.csv]` | Export unlabeled training candidates. | ### Run a local scan dotnet run --project Analyzer.CLI -- . --json The scan path can now be: - a directory - a `.csproj` - a `.sln` ### Export SARIF dotnet run --project Analyzer.CLI -- . --sarif analysis.sarif.json ### Use AI scoring dotnet run --project Analyzer.CLI -- . --ai --min-confidence 0.70 ### Fail the pipeline on severity dotnet run --project Analyzer.CLI -- . --fail-on high ### Sync NVD data dotnet run --project Analyzer.CLI -- sync-nvd --days 7 ### Train the AI model dotnet run --project Analyzer.CLI -- train-ai This now trains from the canonical labeled dataset: - `Analyzer.AI/Training/training-labeled.csv` ## Outputs - `analysis-report.json` - JSON report with summary and findings - `analysis.sarif.json` - SARIF 2.1.0 output for GitHub Code Scanning - `cves.db` - Local SQLite cache for NVD data - `ai-model.zip` - Saved ML.NET model - `ai-model.metadata.json` - model metadata with training date, dataset size, class balance, split seed, evaluation summary, and schema version - `Analyzer.AI/Training/training-labeled.csv` - canonical labeled dataset used for training - `Analyzer.AI/Training/training-candidates.csv` - unlabeled candidate rows exported for manual review and labeling ## Known Gaps These are important and should be treated as real backlog items: - automated tests exist only for a narrow CSV/dataset slice - automated tests are still narrow even after adding scan-input coverage - seven implemented rules - basic configuration file support for disabling rules, excluding paths, suppressing findings, and baseline mode - scan input is now build-aware for project file selection, though metadata reference loading is still lighter than a full design-time build - AI training/export workflow needs stronger dataset hygiene - some context documentation in the repository is now outdated relative to the code ## Documentation - [docs/CODEX_CONTEXT_V2.md](docs/CODEX_CONTEXT_V2.md) - [docs/USER_MANUAL.md](docs/USER_MANUAL.md) - [docs/features/01-project-aware-scan-engine.md](docs/features/01-project-aware-scan-engine.md) - [docs/features/02-automated-test-harness.md](docs/features/02-automated-test-harness.md) - [docs/features/03-sql-injection-taint-analysis.md](docs/features/03-sql-injection-taint-analysis.md) - [docs/features/04-command-injection-rule.md](docs/features/04-command-injection-rule.md) - [docs/features/05-path-traversal-rule.md](docs/features/05-path-traversal-rule.md) - [docs/features/06-insecure-deserialization-rule.md](docs/features/06-insecure-deserialization-rule.md) - [docs/features/07-xxe-and-unsafe-xml-rule.md](docs/features/07-xxe-and-unsafe-xml-rule.md) - [docs/features/08-configuration-suppressions-and-baseline.md](docs/features/08-configuration-suppressions-and-baseline.md) - [docs/features/09-reporting-fingerprints-and-sarif-v2.md](docs/features/09-reporting-fingerprints-and-sarif-v2.md) - [docs/features/10-ai-dataset-and-confidence-pipeline-v2.md](docs/features/10-ai-dataset-and-confidence-pipeline-v2.md) - [docs/academic_logs/2026-04-22-feature-01-slice-2.md](docs/academic_logs/2026-04-22-feature-01-slice-2.md)