# Sanicode Phase 1 MVP Scope

This document defines the boundaries of the Phase 1 MVP: what is in scope, what is not, and the acceptance criteria that mark Phase 1 complete. For the full standards baseline and architecture rationale, see `RESEARCH.md`.

---

## 1. Target Scope

Phase 1 targets **Python 3.10+ codebases** with a single-language focus. Multi-language support via tree-sitter is planned for a later phase.

The analysis surface is deliberately narrow: **input validation, sanitization, and encoding gaps**. These are the highest-leverage findings for compliance frameworks (ASVS, NIST, STIG) and the root cause of the injection-class vulnerabilities that dominate the OWASP Top 10 and CWE Top 25.

---

## 2. MVP CWE Coverage

The MVP detection surface covers four CWEs. They were chosen because they represent the highest-impact sanitization-related weaknesses, together covering the OWASP Top 10 injection category and the CWE Top 25 Most Dangerous Software Weaknesses.

| CWE | Name | Description |
|-----|------|-------------|
| CWE-20 | Improper Input Validation | The software does not validate, or incorrectly validates, input in a way that allows attackers to influence downstream operations. This is the root cause that enables the injection CWEs below. |
| CWE-78 | OS Command Injection | Unsanitized input is incorporated into an OS command, allowing an attacker to execute arbitrary commands on the host. Key patterns: `subprocess`, `os.system`, `os.popen`. |
| CWE-79 | Cross-site Scripting (XSS) | User-controlled data is included in web output without encoding, allowing script injection in a victim's browser. Relevant for Django/Flask/FastAPI templates and direct response construction. |
| CWE-89 | SQL Injection | Unsanitized input is concatenated into SQL queries, allowing database manipulation or exfiltration. Key patterns: f-strings in queries, `.format()` in query strings, raw `execute()` calls. |

These four form a coherent, testable detection set: CWE-20 is the structural root cause; CWE-78, CWE-79, and CWE-89 are the three highest-priority concrete manifestations in web-facing Python code.

---

## 3. CLI Commands in Scope

All six subcommands are in scope for Phase 1. The tool operates in three modes (see Section 4).

```
sanicode config     Configure the LLM backend: set tiered endpoints (fast,
                    analysis, reasoning), validate connectivity, and store
                    credentials in the user config file.

sanicode scan       Scan a target path, build a knowledge graph from AST
                    analysis and (optionally) LLM-assisted data flow reasoning,
                    and persist the result for downstream commands.

sanicode report     Read the knowledge graph produced by `scan` and generate
                    a compliance-mapped report in Markdown, JSON, or SARIF.

sanicode recommend  Produce a prioritized list of remediation actions from
                    the active scan, ordered by severity and compliance impact.

sanicode graph      Inspect or export the knowledge graph: node/edge summary,
                    GraphML export, or JSON adjacency list.

sanicode serve      Start a FastAPI server exposing the sanicode API for
                    remote and hybrid operating modes.
```

---

## 4. Operating Modes

**Local** — all analysis runs in-process on the developer workstation. Suited for small-to-medium codebases where privacy or air-gap requirements prevent outbound calls, or where the developer wants a fast inner loop without a remote endpoint. The knowledge graph lives in memory (NetworkX).

**Remote** — the CLI acts as a thin client to a `sanicode-api` instance running on OpenShift (or any HTTP endpoint started by `sanicode serve`). Scanning and analysis are delegated to the server. Suited for large codebases or shared CI pipelines.

**Hybrid** — AST parsing and graph construction run locally; LLM calls for reachability analysis and remediation guidance are forwarded to the remote endpoint. This is the recommended mode for teams: keeps source code local while leveraging a centrally managed model tier.

All three modes produce identical output formats and compliance mappings.

---

## 5. Output Formats

**Markdown** — human-readable report intended for developer review, PR comments, or ATO documentation packages. Includes finding summaries, compliance cross-references, and remediation guidance.

**JSON** — structured representation of all findings, graph metadata, and compliance mappings. Designed for programmatic consumption by refactoring agents (Konveyor, custom agents) and dashboard ingestion.

**SARIF v2.1.0** — Static Analysis Results Interchange Format. The industry standard for SAST tool output. Consumed natively by GitHub Code Scanning, VS Code (SARIF Viewer), Azure DevOps, and Tekton pipeline gating. SARIF output is the primary integration surface for ecosystem tooling and is treated as a first-class citizen alongside Markdown.

---

## 6. Degraded Mode Contract

Sanicode is **offline-native**. With no LLM endpoint configured, the tool must still produce meaningful, actionable output. Degraded mode is not a fallback — it is a supported operating mode for air-gapped environments and CI pipelines that cannot reach an inference endpoint.

**Available without an LLM endpoint:**

- AST-based pattern matching (Bandit-equivalent detection of known-bad patterns)
- Known-bad function detection: `eval`, `exec`, `subprocess.call(shell=True)`, raw SQL string formatting, unsafe `pickle` usage
- Import analysis (flags imports of known-dangerous modules)
- Data flow graph construction (source → sink paths via AST traversal)
- Compliance cross-reference lookups (CWE → ASVS → NIST → STIG)
- SARIF, JSON, and Markdown output generation

**Requires an LLM endpoint:**

- Context-aware reachability analysis (does this source actually reach this sink through real execution paths?)
- Sanitization adequacy assessment (is the sanitization applied sufficient for the threat model?)
- Natural language remediation guidance
- Cross-file data flow tracing beyond what AST can determine statically
- Framework-aware pattern recognition (Django ORM, SQLAlchemy, Jinja2 autoescape, etc.)
- Confidence scoring and false-positive reduction

The degraded mode output is clearly marked in all output formats. Findings generated without LLM analysis carry a lower default confidence score and note that reachability has not been verified.

---

## 7. Compliance Framework Versions

Every finding carries cross-references to all four frameworks. The specific versions in scope for Phase 1:

| Framework | Version | Key Controls |
|-----------|---------|--------------|
| OWASP ASVS | **5.0** (May 2025) | V1: Encoding and Sanitization (v5.0.0-V1-x.x identifiers) |
| NIST SP 800-53 | **Rev 5** | SI-10 (Information Input Validation), SI-15 (Information Output Filtering) |
| ASD STIG | **v4 r11** | APSC-DV-002510 (Command Injection, CAT I), APSC-DV-002520 (XSS, CAT II), APSC-DV-002530 (Input Validation, CAT II) |
| PCI DSS | **4.0** | Requirement 6 (Secure Systems and Software) — where applicable |

All compliance data ships in the package under `data/`. No egress is required at runtime for compliance lookups.

---

## 8. Explicitly Out of Scope (Phase 1)

The following are planned for later phases and must not be implemented in Phase 1:

- Multi-language support (tree-sitter integration — Phase 2+)
- Kubernetes Operator, CRDs (SanicodeConfig, SanicodeScan, etc.) — Phase 3
- KFP pipeline definitions — Phase 2
- Grafana dashboards and Prometheus alerting rules — Phase 2
- MLflow integration — Phase 2
- Helm chart packaging — Phase 2
- OLM/OperatorHub packaging — Phase 4
- Neo4j persistent graph backend (NetworkX in-memory only for MVP)
- Custom rule authoring UI
- `SanicodeException` CR (RBAC-controlled risk acceptance) — Phase 3

Note: `sanicode serve` exposes `/metrics` (Prometheus format) from Phase 1 as part of the API surface, but dashboards and alerting rules are Phase 2.

---

## 9. Acceptance Criteria

Phase 1 is complete when all of the following are satisfied:

- [ ] `pip install sanicode` works from PyPI (or `pip install -e .` from source)
- [ ] `sanicode --help` displays all six subcommands with descriptions
- [ ] `sanicode config` can set and validate LLM endpoint configuration
- [ ] `sanicode scan <path>` produces a knowledge graph for a Python codebase
- [ ] Degraded mode (no LLM configured) detects at least CWE-78, CWE-79, and CWE-89 patterns via AST analysis
- [ ] `sanicode report` outputs Markdown, JSON, and SARIF (v2.1.0) formats
- [ ] Every finding includes CWE, OWASP ASVS 5.0, NIST 800-53 Rev 5, and ASD STIG v4 r11 cross-references
- [ ] `sanicode serve` starts a FastAPI server with documented REST endpoints (`POST /api/v1/scan`, `GET /api/v1/scan/{id}`, etc.)
- [ ] `sanicode graph` exports the knowledge graph in at least one consumable format (GraphML or JSON)
- [ ] Test coverage is 80% or higher (measured by `pytest --cov`)
- [ ] CI passes on Python 3.10, 3.11, 3.12, and 3.13
