icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-05-security-scanning.md

@@ -0,0 +1,229 @@
+# Phase 5 — Security Scanning
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 5 |
+| Title | Comprehensive Security Scanning Pipeline |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 1 (GOTCHA Framework Foundation), Phase 3 (TDD/BDD Testing Framework) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+A single undetected vulnerability in a government system can be a national security incident. No single security scanning tool catches everything -- static analysis finds code-level flaws but misses dependency vulnerabilities; dependency auditors find known CVEs but miss hardcoded secrets; secret detectors find credentials but miss container misconfigurations. Defense-in-depth requires layering multiple complementary scanners and aggregating their results.
+
+Traditional security scanning is performed as a late-stage gate, often as a checkbox exercise before deployment. By this point, the cost of remediation is high, schedules are compressed, and pressure mounts to accept risk rather than fix findings. In government environments, this pattern leads to POAMs full of overdue items and eventual ATO revocation.
+
+ICDEV integrates a comprehensive 4-scanner security pipeline that runs early and often: SAST (static application security testing) via Bandit, dependency auditing via pip-audit, secret detection via detect-secrets, and container scanning via Trivy. Quality gates enforce zero tolerance for critical/high findings and detected secrets. Findings feed directly into POAM generation (Phase 4). The pipeline blocks deployment until all gates pass -- no exceptions without Authorizing Official written approval.
+
+---
+
+## 2. Goals
+
+1. Run Static Application Security Testing (SAST) using Bandit (Python), eslint-security (JavaScript), SpotBugs (Java), gosec (Go), cargo-audit (Rust), SecurityCodeScan (C#)
+2. Audit all dependencies (direct and transitive) against CVE databases using pip-audit, npm audit, OWASP Dependency Check, govulncheck, or dotnet list
+3. Detect hardcoded secrets (API keys, passwords, private keys, tokens, connection strings) using detect-secrets with zero tolerance
+4. Scan container images for OS-level and application-level vulnerabilities using Trivy
+5. Enforce quality gates that block deployment: 0 critical/high vulnerabilities, 0 detected secrets, 0 CAT1 STIG findings
+6. Generate a consolidated security report aggregating all scanner results
+7. Feed all findings into the POAM generation pipeline for compliance traceability
+
+---
+
+## 3. Architecture
+
+### 3.1 Security Scanning Pipeline
+
+```
++--------+     +--------+     +--------+     +--------+
+| SAST   |---->| Dep    |---->| Secret |---->|Container|
+| Scanner|     | Audit  |     | Detect |     | Scanner |
+| bandit |     |pip-audit|    |detect- |     | trivy   |
+|        |     |        |     |secrets |     |         |
++---+----+     +---+----+     +---+----+     +---+----+
+    |              |              |              |
+    v              v              v              v
++-------+     +-------+     +-------+     +-------+
+| Gate 1|     | Gate 2|     | Gate 3|     | Gate 4|
+| 0 crit|     | 0 crit|     | 0 sec |     | 0 crit|
+| 0 high|     | 0 high|     | rets  |     | 0 high|
++---+---+     +---+---+     +---+---+     +---+---+
+    |              |              |              |
+    +------+-------+------+------+------+-------+
+           |              |             |
+           v              v             v
+       ALL PASS?      ANY FAIL?    CONSOLIDATED
+       Proceed to     BLOCKED:     SECURITY
+       compliance     Remediate    REPORT
+       workflow       findings     (Step 6)
+```
+
+### 3.2 Quality Gates
+
+| Gate | Threshold | Blocks Deployment |
+|------|-----------|-------------------|
+| Critical vulnerabilities (SAST) | 0 | YES |
+| High vulnerabilities (SAST) | 0 | YES |
+| Detected secrets | 0 | YES |
+| CAT1 STIG findings | 0 | YES |
+| High dependency vulnerabilities | 0 | YES |
+| Medium dependency vulnerabilities | <= 5 with documented POAM | NO (with POAM) |
+| Low findings | Unlimited | NO |
+
+### 3.3 Scanner Coverage by Language
+
+| Language | SAST | Dep Audit | Secret Detection | Container |
+|----------|------|-----------|-----------------|-----------|
+| Python | Bandit | pip-audit | detect-secrets | Trivy |
+| Java | SpotBugs | OWASP Dependency Check | detect-secrets | Trivy |
+| JavaScript/TS | eslint-security | npm audit | detect-secrets | Trivy |
+| Go | gosec | govulncheck | detect-secrets | Trivy |
+| Rust | cargo-audit | cargo-audit | detect-secrets | Trivy |
+| C# | SecurityCodeScan | dotnet list | detect-secrets | Trivy |
+
+---
+
+## 4. Requirements
+
+### 4.1 SAST
+
+#### REQ-05-001: Static Analysis Execution
+The system SHALL run language-appropriate SAST scanners against all source code in the project directory.
+
+#### REQ-05-002: Finding Classification
+SAST findings SHALL be classified by severity (CRITICAL, HIGH, MEDIUM, LOW) and include file path, line number, and CWE reference.
+
+#### REQ-05-003: False Positive Management
+The system SHALL support `# nosec` comment annotations for documented false positives with justification recorded in the POAM.
+
+### 4.2 Dependency Audit
+
+#### REQ-05-004: Transitive Dependency Scanning
+The dependency auditor SHALL scan all direct and transitive dependencies, not just top-level declarations.
+
+#### REQ-05-005: CVE Correlation
+Each vulnerability finding SHALL include the CVE identifier, affected package version, and recommended fix version.
+
+#### REQ-05-006: Unfixable Vulnerabilities
+When a vulnerability has no available fix, the system SHALL document it in the POAM with "vendor dependency" status.
+
+### 4.3 Secret Detection
+
+#### REQ-05-007: Zero Tolerance
+The secret detection gate SHALL enforce zero detected secrets. Any detection is a gate failure.
+
+#### REQ-05-008: Secret Types
+The detector SHALL identify API keys, passwords, private keys, tokens, and connection strings across all source files.
+
+#### REQ-05-009: Immediate Rotation
+When secrets are detected, the system SHALL recommend immediate credential rotation and provide remediation steps (remove from code, add to .gitignore, verify git history).
+
+#### REQ-05-010: Baseline Management
+The system SHALL support a `.secrets.baseline` file for documenting allowed patterns with justification.
+
+### 4.4 Container Scanning
+
+#### REQ-05-011: OS and Application Scanning
+The container scanner SHALL check both OS-level packages and application-level dependencies within the container image.
+
+#### REQ-05-012: Misconfiguration Detection
+The container scanner SHALL check for misconfigurations: running as root, secrets in image, writable filesystem.
+
+#### REQ-05-013: Skip Conditions
+Container scanning SHALL be skipped (marked N/A) when no Dockerfile exists or Docker is not running, without failing the overall pipeline.
+
+### 4.5 Reporting and Integration
+
+#### REQ-05-014: Consolidated Report
+The system SHALL generate a consolidated security report aggregating findings from all scanners with severity rollups, top risks, and remediation recommendations.
+
+#### REQ-05-015: POAM Feed
+All findings SHALL be available for import by the POAM generator (Phase 4) with severity-appropriate timelines.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `security_findings` | Aggregated findings from all scanners with severity, CVE, CWE, file, line |
+| `audit_trail` | Append-only log of scan executions and gate results |
+| `sbom_components` | Component inventory for dependency correlation |
+| `prompt_injection_log` | Prompt injection detection events (Phase 37 extension) |
+| `ai_telemetry` | AI usage telemetry with SHA-256 hashed prompts/responses |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/security/sast_runner.py` | Run static application security testing (Bandit, eslint-security, etc.) |
+| `tools/security/dependency_auditor.py` | Audit dependencies against CVE databases (pip-audit, npm audit, etc.) |
+| `tools/security/secret_detector.py` | Detect hardcoded secrets in source code (detect-secrets) |
+| `tools/security/container_scanner.py` | Scan container images for vulnerabilities (Trivy) |
+| `tools/security/code_pattern_scanner.py` | Detect dangerous code patterns across 6 languages |
+| `tools/audit/audit_logger.py` | Log scan events and gate results to audit trail |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D5 | CUI markings applied at generation time | Security reports carry classification markings from creation |
+| D6 | Audit trail is append-only/immutable | Scan results cannot be retroactively modified; NIST AU compliance |
+| D278 | Dangerous pattern detection: unified scanner across 6 languages | Callable from marketplace, translation, child app generation, and security scanning; declarative YAML patterns |
+
+---
+
+## 8. Security Gate
+
+**Security Scanning Gate (Code Review & Merge):**
+- 0 critical/high SAST findings
+- 0 critical/high dependency vulnerabilities
+- 0 detected secrets
+- 0 critical container vulnerabilities (or N/A if no containers)
+- No exceptions without Authorizing Official written approval
+
+**Code Patterns Gate:**
+- max_critical = 0
+- max_high = 0
+- max_medium = 10
+
+**Scan Frequency:**
+- Every commit: incremental SAST on changed files
+- Every merge request: full pipeline (all 4 scanners)
+- Weekly: full deep scan
+- Emergency: zero-day CVE response triggers immediate scan
+
+---
+
+## 9. Commands
+
+```bash
+# Individual scanners
+python tools/security/sast_runner.py --project-dir "/path"
+python tools/security/dependency_auditor.py --project-dir "/path"
+python tools/security/secret_detector.py --project-dir "/path"
+python tools/security/container_scanner.py --image "my-image:latest"
+
+# Dangerous code pattern detection
+python tools/security/code_pattern_scanner.py --project-dir "/path" --json
+python tools/security/code_pattern_scanner.py --project-dir "/path" --gate --json
+
+# Security skill (runs full pipeline)
+/icdev-secure    # Run security scanning (SAST, deps, secrets, container)
+
+# Audit logging
+python tools/audit/audit_logger.py --event-type "security_scan_complete" \
+  --actor "security-agent" --action "Scan completed" --project-id "proj-123"
+```

icdev/data/docs/features/phase-06-infrastructure-deployment.md

@@ -0,0 +1,288 @@
+# Phase 6 — Infrastructure & Deployment
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 6 |
+| Title | Infrastructure as Code & Deployment Pipeline |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 3 (TDD/BDD Testing Framework), Phase 4 (NIST 800-53 Compliance), Phase 5 (Security Scanning) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Manual deployments are unreproducible, error-prone, and unauditable. In government environments, every infrastructure change must be tracked, reviewed, approved, and reversible. A deployment that cannot be reproduced from version-controlled artifacts is a compliance violation. A deployment that cannot be rolled back is an operational risk. A deployment without security gates is a security incident waiting to happen.
+
+The gap between "code works on my machine" and "code runs securely in GovCloud" is enormous. Applications require hardened infrastructure (STIG-compliant OS, encrypted storage, least-privilege IAM, private networking), orchestration (Kubernetes with security contexts, network policies, pod disruption budgets), configuration management (Ansible with vault-encrypted secrets), and a multi-stage CI/CD pipeline that enforces security gates between every stage.
+
+ICDEV generates all infrastructure-as-code artifacts deterministically from project configuration: Terraform for cloud resources (AWS GovCloud by default, multi-cloud via Phase 38), Ansible for STIG-hardened configuration management, Kubernetes manifests with security-hardened pod specifications, and a 7-stage GitLab CI/CD pipeline with gates between every stage. A 10-gate pre-deployment verification ensures no artifact ships without passing all security, compliance, and quality checks. Rollback capability provides immediate recovery when deployments fail.
+
+---
+
+## 2. Goals
+
+1. Generate Terraform configurations for AWS GovCloud infrastructure with encrypted storage, least-privilege IAM, private networking, and S3+DynamoDB state locking
+2. Generate Ansible playbooks with STIG hardening roles, vault-encrypted secrets, SSH key authentication, and audit logging
+3. Generate Kubernetes manifests with security-hardened pod specifications (non-root, read-only rootfs, no privilege escalation, resource limits, network policies)
+4. Generate a 7-stage GitLab CI/CD pipeline (build, test, SAST, dependency, container, compliance, deploy) with gates between stages
+5. Enforce 10 pre-deployment gates before any commit to deployment branch
+6. Provide rollback capability for immediate recovery from failed deployments
+7. Support multi-environment deployment: dev (auto on merge), staging (auto on tag), production (manual approval required)
+
+---
+
+## 3. Architecture
+
+### 3.1 Deployment Pipeline
+
+```
++----------+    +----------+    +----------+    +----------+
+| Terraform|--->| Ansible  |--->|    K8s   |--->| Pipeline |
+| Generate |    | Generate |    | Generate |    | Generate |
+| IaC      |    | Playbooks|    | Manifests|    | CI/CD    |
++----------+    +----------+    +----------+    +----+-----+
+                                                     |
+                                                     v
+                                              +-------------+
+                                              | 10 Pre-     |
+                                              | Deploy Gates|
+                                              +------+------+
+                                                     |
+                                         +-----------+-----------+
+                                         |                       |
+                                    ALL PASS               ANY FAIL
+                                         |                       |
+                                         v                       v
+                                   +-----------+          +----------+
+                                   | Commit &  |          | BLOCKED  |
+                                   | Push      |          | Remediate|
+                                   +-----+-----+          +----------+
+                                         |
+                                         v
+                                   +-----------+
+                                   | 7-Stage   |
+                                   | Pipeline  |
+                                   | Execution |
+                                   +-----+-----+
+                                         |
+                                    +----+----+
+                                    |         |
+                                  PASS      FAIL
+                                    |         |
+                                    v         v
+                              +---------+ +----------+
+                              | Health  | | Rollback |
+                              | Check + | |          |
+                              | Audit   | +----------+
+                              +---------+
+```
+
+### 3.2 7-Stage CI/CD Pipeline
+
+```
+Stage 1: BUILD -----> Stage 2: TEST -----> Stage 3: SAST
+  Compile, package      Unit tests           Static analysis
+  Container image       Coverage >= 80%      0 critical/high
+         |                    |                    |
+         v                    v                    v
+Stage 4: DEPS -----> Stage 5: CONTAINER -> Stage 6: COMPLIANCE
+  pip-audit             trivy scan           STIG check
+  0 critical/high       0 critical           CUI markings
+         |                    |                    |
+         v                    v                    v
+                     Stage 7: DEPLOY
+                       Terraform apply
+                       Ansible run
+                       K8s deploy
+                       (manual for prod)
+```
+
+### 3.3 Generated Terraform Structure
+
+```
+infrastructure/terraform/
+  +-- main.tf              # Provider, backend, core resources
+  +-- variables.tf         # Input variables
+  +-- outputs.tf           # Output values
+  +-- networking.tf        # VPC, subnets, security groups
+  +-- compute.tf           # EC2/ECS/EKS resources
+  +-- storage.tf           # S3, RDS, EBS
+  +-- iam.tf               # IAM roles, policies (least privilege)
+  +-- security_groups.tf   # Network ACLs
+  +-- terraform.tfvars     # Environment-specific values
+```
+
+---
+
+## 4. Requirements
+
+### 4.1 Terraform
+
+#### REQ-06-001: GovCloud Provider
+Generated Terraform SHALL target AWS GovCloud (us-gov-west-1) by default with S3+DynamoDB state locking.
+
+#### REQ-06-002: Encryption at Rest
+All S3 buckets and RDS instances SHALL have encryption enabled. No unencrypted storage resources.
+
+#### REQ-06-003: Least Privilege IAM
+Generated IAM policies SHALL follow least-privilege: no wildcard (*) actions, scoped to specific resources.
+
+#### REQ-06-004: Network Isolation
+Compute resources SHALL reside in private subnets. Only load balancers may have public-facing ingress on port 443.
+
+#### REQ-06-005: No Hardcoded Secrets
+Terraform configurations SHALL reference CI/CD variables or AWS Secrets Manager, never contain hardcoded credentials.
+
+### 4.2 Ansible
+
+#### REQ-06-006: STIG Hardening Role
+Generated Ansible playbooks SHALL include a STIG hardening role that automates applicable STIG checks.
+
+#### REQ-06-007: Vault-Encrypted Secrets
+All sensitive values in Ansible playbooks SHALL use Ansible Vault encryption, never plaintext.
+
+#### REQ-06-008: SSH Key Authentication
+Ansible configurations SHALL enforce SSH key-based authentication only, no password authentication.
+
+### 4.3 Kubernetes
+
+#### REQ-06-009: Security Context
+All generated K8s pod specifications SHALL include: `runAsNonRoot: true`, `readOnlyRootFilesystem: true`, `allowPrivilegeEscalation: false`, and resource limits.
+
+#### REQ-06-010: Network Policies
+Generated K8s manifests SHALL include NetworkPolicy resources restricting pod-to-pod traffic (default deny).
+
+#### REQ-06-011: Image Pinning
+All container image references SHALL use specific version tags, never `latest`.
+
+#### REQ-06-012: RBAC
+Generated K8s manifests SHALL include ServiceAccount, Role, and RoleBinding resources following least-privilege.
+
+### 4.4 Pipeline
+
+#### REQ-06-013: 7-Stage Pipeline
+The generated GitLab CI/CD pipeline SHALL include 7 stages: build, test, sast, dependency, container, compliance, deploy.
+
+#### REQ-06-014: Fail-Fast
+Each pipeline stage SHALL fail fast -- no continuing past failures to subsequent stages.
+
+#### REQ-06-015: Production Manual Approval
+Production deployment SHALL require manual approval. Dev and staging may deploy automatically.
+
+#### REQ-06-016: Artifact Retention
+All pipeline artifacts (test reports, scan results, SBOM) SHALL be retained for 90 days.
+
+### 4.5 Pre-Deployment Gates
+
+#### REQ-06-017: 10-Gate Verification
+The system SHALL verify 10 gates before deployment: (1) all tests pass, (2) coverage >= 80%, (3) 0 critical/high SAST, (4) 0 critical/high deps, (5) 0 secrets, (6) 0 critical container vulns, (7) 0 CAT1 STIG, (8) CUI markings present, (9) SBOM current (<30 days), (10) ATO status valid.
+
+### 4.6 Rollback
+
+#### REQ-06-018: Rollback Capability
+The system SHALL provide rollback to the last known-good deployment via `tools/infra/rollback.py` when post-deployment health checks fail.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `deployments` | Deployment records with environment, status, commit hash, pipeline ID |
+| `projects` | Project metadata including ATO status and deployment history |
+| `audit_trail` | Append-only log of deployment events and gate results |
+| `agents` | Infrastructure agent (port 8448) registration and health |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/infra/terraform_generator.py` | Generate Terraform configurations for cloud infrastructure |
+| `tools/infra/ansible_generator.py` | Generate Ansible playbooks with STIG hardening roles |
+| `tools/infra/k8s_generator.py` | Generate security-hardened Kubernetes manifests |
+| `tools/infra/pipeline_generator.py` | Generate 7-stage GitLab CI/CD pipeline |
+| `tools/infra/rollback.py` | Roll back to last known-good deployment |
+| `tools/monitor/health_checker.py` | Post-deployment health check with retry |
+| `tools/audit/audit_logger.py` | Log deployment events to append-only audit trail |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D1 | SQLite for ICDEV internals; PostgreSQL for apps ICDEV builds | Generated applications get production-grade databases |
+| D3 | Flask over FastAPI | Simpler, fewer dependencies, auditable SSR, smaller STIG attack surface |
+| D141 | HPA with CPU/memory metrics as baseline | Cloud-agnostic auto-scaling; works on EKS, GKE, AKS, OpenShift |
+| D143 | PDB with minAvailable=1 for core agents | Guarantees availability during rolling updates and node maintenance |
+| D226 | Multi-cloud Terraform generators produce CSP-specific IaC | Azure Gov, GCP Assured Workloads, OCI Gov, IBM IC4G, on-prem K8s/Docker |
+| D229 | Helm value overlays per CSP | CSP-specific K8s config without modifying base templates |
+
+---
+
+## 8. Security Gate
+
+**Deploy Gate:**
+- Staging tests pass
+- Compliance artifacts current (within 30 days)
+- Change request approved
+- Rollback plan exists
+
+**Pre-Deployment Gate (10 checks):**
+1. All tests pass
+2. Coverage >= 80%
+3. SAST -- 0 critical/high
+4. Dependencies -- 0 critical/high
+5. Secrets -- 0 detected
+6. Container -- 0 critical/high (or N/A)
+7. STIG -- 0 CAT1
+8. CUI markings present
+9. SBOM current (< 30 days)
+10. ATO status valid
+
+**Container Security:**
+- All containers: read-only rootfs, drop ALL capabilities, non-root (UID 1000), resource limits enforced
+- STIG-hardened base images for all agents and services
+
+---
+
+## 9. Commands
+
+```bash
+# Infrastructure generation
+python tools/infra/terraform_generator.py --project-id "proj-123"
+python tools/infra/ansible_generator.py --project-id "proj-123"
+python tools/infra/k8s_generator.py --project-id "proj-123"
+python tools/infra/pipeline_generator.py --project-id "proj-123"
+
+# Multi-cloud Terraform (Phase 38 extension)
+python tools/infra/terraform_generator.py --project-id "proj-123" --csp azure
+python tools/infra/terraform_generator.py --project-id "proj-123" --csp gcp
+python tools/infra/terraform_generator.py --project-id "proj-123" --csp oci
+
+# Rollback
+python tools/infra/rollback.py --deployment-id "deploy-123"
+
+# Health check
+python tools/monitor/health_checker.py --target "http://service:8080/health"
+
+# K8s auto-scaling (Phase 38 extension)
+kubectl apply -f k8s/hpa.yaml
+kubectl apply -f k8s/pdb.yaml
+
+# Deployment skill
+/icdev-deploy    # Generate IaC and deploy via GitLab CI/CD
+
+# Audit logging
+python tools/audit/audit_logger.py --event-type "deployment_complete" \
+  --actor "infra-agent" --action "Deploy to staging" --project-id "proj-123"
+```