icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-07-code-review-gates.md

@@ -0,0 +1,276 @@
+# Phase 7 — Code Review Gates
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 7 |
+| Title | Enforced Code Review Gates |
+| 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
+
+Code review in government software development is not optional -- it is a compliance requirement. NIST 800-53 controls SA-11 (Developer Testing and Evaluation), SA-15 (Development Process, Standards, and Tools), and CM-3 (Configuration Change Control) mandate that code changes undergo structured review before integration. Without automated enforcement, review gates are bypassed under schedule pressure, leading to security vulnerabilities, compliance gaps, and audit findings.
+
+Traditional code review focuses on readability and logic correctness. In government environments, review must also verify security posture (no SAST findings, no secrets, no vulnerable dependencies), compliance posture (CUI markings present, STIG checks passing, SBOM current), and quality posture (all tests passing, coverage adequate, linting clean). These checks cannot rely on human diligence alone -- they must be automated, gated, and logged to an immutable audit trail.
+
+ICDEV implements an 8-step automated code review gate that evaluates every merge request across all three dimensions: security, compliance, and quality. All gates must pass for merge approval. Any failure blocks the merge with specific remediation guidance. Every gate decision is recorded in the append-only audit trail, satisfying NIST AU controls and providing assessors with evidence of configuration change control.
+
+---
+
+## 2. Goals
+
+1. Enforce automated code review gates that block merge when security, compliance, or quality standards are not met
+2. Run the full test suite (pytest unit tests + behave BDD tests) with coverage verification as the first gate
+3. Execute the complete security scanning pipeline (SAST, dependency audit, secret detection, container scan) as part of review
+4. Verify STIG compliance with 0 CAT1 tolerance
+5. Verify CUI markings are present on all source files and compliance documents
+6. Verify SBOM currency (reflects current dependencies)
+7. Record every gate decision in the append-only audit trail with NIST 800-53 SA-11, SA-15, and CM-3 control mappings
+8. Provide specific remediation guidance for every gate failure, not just pass/fail status
+
+---
+
+## 3. Architecture
+
+### 3.1 Review Gate Pipeline
+
+```
++------------------------------------------------------------------+
+|                    CODE REVIEW GATE PIPELINE                      |
+|                                                                   |
+|  Step 1         Step 2          Step 3          Step 4            |
+|  +---------+    +-----------+   +-----------+   +-----------+     |
+|  | TEST    |--->| SECURITY  |-->| STIG      |-->| CUI       |    |
+|  | SUITE   |    | SCAN      |   | CHECK     |   | VERIFY    |    |
+|  |         |    |           |   |           |   |           |    |
+|  | pytest  |    | SAST      |   | 0 CAT1    |   | All files |    |
+|  | behave  |    | deps      |   | findings  |   | marked    |    |
+|  | cov>=80%|    | secrets   |   |           |   |           |    |
+|  +---------+    | container |   +-----------+   +-----------+    |
+|                 +-----------+                                     |
+|                                                                   |
+|  Step 5         Step 6          Step 7          Step 8            |
+|  +---------+    +-----------+   +-----------+   +-----------+     |
+|  | SBOM    |--->| LINT      |-->| GATE      |-->| AUDIT     |    |
+|  | VERIFY  |    | CHECK     |   | DECISION  |   | TRAIL     |    |
+|  |         |    |           |   |           |   |           |    |
+|  | Current |    | 0 critical|   | ALL PASS  |   | SA-11     |    |
+|  | deps    |    | errors    |   | = APPROVE |   | SA-15     |    |
+|  | match   |    |           |   | ANY FAIL  |   | CM-3      |    |
+|  |         |    |           |   | = REJECT  |   |           |    |
+|  +---------+    +-----------+   +-----------+   +-----------+    |
++------------------------------------------------------------------+
+```
+
+### 3.2 Gate Decision Matrix
+
+```
+                    ALL GATES PASS           ANY GATE FAILS
+                    +-------------+          +---------------+
+                    |             |          |               |
+                    v             |          v               |
+              +-----------+      |    +-----------+         |
+              | APPROVE   |      |    | REJECT    |         |
+              | Merge     |      |    | Block     |         |
+              | allowed   |      |    | merge     |         |
+              +-----------+      |    +-----------+         |
+                    |            |          |               |
+                    v            |          v               |
+              +-----------+      |    +-----------+         |
+              | Audit     |      |    | Report    |         |
+              | trail     |      |    | ALL fails |         |
+              | entry:    |      |    | with      |         |
+              | APPROVED  |      |    | remediation|        |
+              +-----------+      |    | guidance   |        |
+                                 |    +-----------+         |
+                                 |                          |
+                                 +--------------------------+
+                                   Both decisions logged
+                                   to audit trail
+```
+
+### 3.3 NIST Control Mapping
+
+| Gate | NIST 800-53 Control | Requirement |
+|------|---------------------|-------------|
+| Test Suite | SA-11 | Developer testing and evaluation |
+| Security Scan | SA-11, RA-5 | Vulnerability analysis, risk assessment |
+| STIG Check | CM-6 | Configuration settings |
+| CUI Markings | SC-16, MP-3 | Information classification, media marking |
+| SBOM Verify | CM-8 | System component inventory |
+| Lint Check | SA-15 | Development standards and tools |
+| Gate Decision | CM-3 | Configuration change control |
+| Audit Trail | AU-2, AU-3 | Audit events, content of audit records |
+
+---
+
+## 4. Requirements
+
+### 4.1 Test Suite Gate
+
+#### REQ-07-001: Full Test Execution
+The review gate SHALL execute all unit tests (pytest) and all BDD tests (behave) for the project.
+
+#### REQ-07-002: Coverage Threshold
+Code coverage SHALL be measured and must meet or exceed 80%. Coverage below 80% is a blocking condition.
+
+#### REQ-07-003: Zero Failure Tolerance
+All tests MUST pass with 0 failures. Any test failure blocks the merge.
+
+### 4.2 Security Scan Gate
+
+#### REQ-07-004: SAST Clean
+The review gate SHALL run SAST analysis and block merge on any critical or high findings.
+
+#### REQ-07-005: Dependency Audit
+The review gate SHALL run dependency audit and block merge on any critical CVE findings.
+
+#### REQ-07-006: Secret Detection
+The review gate SHALL run secret detection with zero tolerance -- any detected secret blocks the merge.
+
+#### REQ-07-007: Container Scan
+When applicable, the review gate SHALL run container scanning and block merge on critical/high findings.
+
+### 4.3 Compliance Gate
+
+#### REQ-07-008: STIG Compliance
+The review gate SHALL run STIG compliance checks against applicable profiles and block merge on any CAT1 finding.
+
+#### REQ-07-009: CUI Marking Verification
+The review gate SHALL verify that all source files have CUI header banners and all documents have CUI banners and designation indicators.
+
+#### REQ-07-010: SBOM Currency
+The review gate SHALL generate a current SBOM and verify it reflects current dependencies. Stale SBOMs block merge.
+
+### 4.4 Quality Gate
+
+#### REQ-07-011: Lint Check
+The review gate SHALL run language-appropriate linting and block merge on critical errors (warnings acceptable).
+
+### 4.5 Decision and Audit
+
+#### REQ-07-012: All-or-Nothing Decision
+ALL gates MUST pass for merge approval. ANY single failure blocks the merge.
+
+#### REQ-07-013: Complete Failure Reporting
+When multiple gates fail, the system SHALL report ALL failures (not just the first one) with specific remediation guidance for each.
+
+#### REQ-07-014: Audit Trail Entry
+Every gate decision (approve or reject) SHALL be recorded in the append-only audit trail with event type `code.review`, all gate results, decision, and timestamp.
+
+#### REQ-07-015: Unavailable Tool Handling
+If a gate tool is unavailable, the gate SHALL be marked UNKNOWN and the overall decision SHALL be REJECT.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `audit_trail` | Append-only log of code review gate decisions with per-gate results |
+| `nist_controls` | NIST 800-53 control evidence from review gates (SA-11, SA-15, CM-3) |
+| `security_findings` | Findings discovered during review scan |
+| `projects` | Project quality metrics including review history |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/builder/linter.py` | Run language-appropriate linting (flake8/ruff, eslint, checkstyle) |
+| `tools/builder/formatter.py` | Run language-appropriate formatting (black, prettier) |
+| `tools/security/sast_runner.py` | Run SAST analysis as part of review |
+| `tools/security/dependency_auditor.py` | Run dependency audit as part of review |
+| `tools/security/secret_detector.py` | Run secret detection as part of review |
+| `tools/security/container_scanner.py` | Run container scanning as part of review |
+| `tools/compliance/stig_checker.py` | Run STIG compliance checks as part of review |
+| `tools/compliance/cui_marker.py` | Verify CUI markings on all files |
+| `tools/compliance/sbom_generator.py` | Generate and verify SBOM currency |
+| `tools/audit/audit_logger.py` | Log gate decisions to append-only audit trail |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D5 | CUI markings applied at generation time | Review gate verifies markings exist; no unmarked code merges |
+| D6 | Audit trail is append-only/immutable | Gate decisions cannot be retroactively modified; CM-3 evidence |
+| D155 | Shared conftest.py centralizes test setup | Consistent test behavior across review runs |
+
+---
+
+## 8. Security Gate
+
+**Code Review Gate (Blocking Conditions):**
+- >= 1 approval required (human reviewer)
+- All comments resolved
+- SAST clean (0 critical/high)
+- No secrets detected (0 tolerance)
+- CUI markings present on all files
+- Tests 100% pass
+- Coverage >= 80% (warning threshold)
+- STIG 0 CAT1 (blocking)
+- Dependencies 0 critical (blocking)
+- SBOM current (warning)
+- Lint 0 critical errors (warning)
+
+**Gate Severity Classification:**
+
+| Gate | Threshold | Severity |
+|------|-----------|----------|
+| Tests | 100% pass | Blocking |
+| Coverage | >= 80% | Warning |
+| SAST | 0 HIGH | Blocking |
+| Dependencies | 0 CRITICAL | Blocking |
+| Secrets | 0 detected | Blocking |
+| STIG | 0 CAT1 | Blocking |
+| CUI | 100% marked | Blocking |
+| SBOM | Current | Warning |
+| Lint | 0 critical | Warning |
+
+---
+
+## 9. Commands
+
+```bash
+# Code review skill (runs full gate pipeline)
+/icdev-review    # Enforce code review gates with security checks
+
+# Individual gate checks (for debugging)
+# Step 1: Test suite
+pytest tests/ -v --tb=short --cov=src --cov-report=term-missing
+
+# Step 2: Security scan
+python tools/security/sast_runner.py --project-dir "/path" --gate
+python tools/security/dependency_auditor.py --project-dir "/path" --gate
+python tools/security/secret_detector.py --project-dir "/path" --gate
+python tools/security/container_scanner.py --image "my-image:latest"
+
+# Step 3: STIG check
+python tools/compliance/stig_checker.py --project-id "proj-123"
+
+# Step 4: CUI verification
+python tools/compliance/cui_marker.py --directory "/path" --verify
+
+# Step 5: SBOM currency
+python tools/compliance/sbom_generator.py --project-dir "/path"
+
+# Step 6: Lint check
+python tools/builder/linter.py --project-dir "/path"
+
+# Audit logging
+python tools/audit/audit_logger.py --event-type "code.review" \
+  --actor "orchestrator" --action "Gate evaluation: APPROVED" \
+  --project-id "proj-123"
+```

icdev/data/docs/features/phase-08-self-healing.md

@@ -0,0 +1,223 @@
+# Phase 8 — Self-Healing System
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 8 |
+| Title | Self-Healing System |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 7 (Security Scanning), Phase 9 (Monitoring & Observability) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Production systems built by ICDEV inevitably encounter failures: services crash, dependencies degrade, configurations drift, and deployments introduce regressions. Without automated remediation, every incident requires human intervention, creating bottlenecks that violate SLA targets and leave Gov/DoD systems vulnerable during the gap between detection and resolution.
+
+Manual incident response is too slow for mission-critical systems operating at IL4/IL5/IL6 impact levels. An operator may take 15-30 minutes to diagnose and fix a known issue that has been solved before. Meanwhile, the system is degraded or offline, impacting warfighter readiness and operational availability.
+
+The Self-Healing System closes this gap by maintaining a growing knowledge base of failure patterns and their proven remediations. When monitoring detects an anomaly, the system matches it against known patterns, evaluates confidence, and either auto-remediates (high confidence), suggests a fix (medium confidence), or escalates with full diagnostic context (low confidence). Every successful fix strengthens the knowledge base, creating a positive feedback loop where the system becomes more resilient over time.
+
+---
+
+## 2. Goals
+
+1. Detect production issues automatically by matching error patterns, log anomalies, and metric threshold breaches against a knowledge base of known failure signatures
+2. Apply a 3-tier confidence-based decision engine that auto-remediates at >= 0.7 confidence, suggests fixes at 0.3-0.7, and escalates with full context below 0.3
+3. Enforce rate limiting (max 5 auto-heal actions per hour, 10-minute cooldown between identical actions) to prevent remediation storms and cascading failures
+4. Implement a feedback loop where successful remediations increase pattern confidence by 0.05 and failures decrease it by 0.1, enabling continuous learning
+5. Use Bedrock LLM for root cause analysis when no pattern match exists, generating new pattern candidates for human review
+6. Record all self-healing events in the append-only audit trail for NIST IR-4, IR-5, and SI-5 compliance
+7. Support cross-project pattern sharing so a fix learned in one project benefits all future projects
+8. Prevent remediation loops with a maximum of 3 retries per pattern per incident and circuit breaker protection
+
+---
+
+## 3. Architecture
+
+```
++-----------------------------------------------------------+
+|                    Monitoring Layer                         |
+|  +------------+  +---------------+  +------------------+   |
+|  | Log        |  | Metric        |  | Alert            |   |
+|  | Analyzer   |  | Collector     |  | Correlator       |   |
+|  +-----+------+  +-------+-------+  +--------+---------+   |
+|        |                  |                   |             |
++--------+------------------+-------------------+-------------+
+         |                  |                   |
+         v                  v                   v
++-----------------------------------------------------------+
+|                 Pattern Detection Engine                    |
+|  +--------------------------------------------------------+|
+|  | Knowledge Base (knowledge_patterns table)              ||
+|  | BM25 keyword + frequency analysis + time correlation   ||
+|  +--------------------------------------------------------+|
++----------------------------+------------------------------+
+                             |
+                             v
++-----------------------------------------------------------+
+|              Root Cause Analyzer                           |
+|  +------------------+  +-----------------------------+    |
+|  | Pattern Match    |  | Bedrock LLM Analysis        |    |
+|  | (known issues)   |  | (unknown issues)            |    |
+|  +--------+---------+  +-------------+---------------+    |
++-----------|----------------------------|-----------------+
+            |                            |
+            v                            v
++-----------------------------------------------------------+
+|              Decision Engine (3-Tier)                      |
+|                                                           |
+|  >= 0.7 + auto_healable  -->  AUTO-REMEDIATE              |
+|  >= 0.7 + !auto_healable -->  SUGGEST (require approval)  |
+|  0.3 - 0.7               -->  SUGGEST (require approval)  |
+|  < 0.3                   -->  ESCALATE (full context)     |
+|                                                           |
+|  Rate Limiter: 5/hour, 10-min cooldown per target         |
++----------------------------+------------------------------+
+                             |
+                             v
++-----------------------------------------------------------+
+|              Remediation Engine                            |
+|  Actions: restart, scale, clear cache, rollback,          |
+|           config fix, dependency update                   |
++----------------------------+------------------------------+
+                             |
+                             v
++-----------------------------------------------------------+
+|              Feedback Loop                                |
+|  Success: confidence += 0.05 (max 1.0), use_count++      |
+|  Failure: confidence -= 0.1, log failure reason           |
+|  Record in self_healing_events (append-only)              |
++-----------------------------------------------------------+
+```
+
+---
+
+## 4. Requirements
+
+### 4.1 Pattern Detection
+
+#### REQ-08-001: Knowledge Base Pattern Matching
+The system SHALL maintain a knowledge base of failure patterns in the `knowledge_patterns` table, each with a signature, root cause description, remediation steps, confidence score, and use count.
+
+#### REQ-08-002: Statistical Matching
+The system SHALL use statistical methods (BM25 keyword matching, frequency analysis, time correlation) for pattern matching against incoming error data. No GPU is required.
+
+#### REQ-08-003: Bedrock LLM Root Cause Analysis
+When no pattern match is found, the system SHALL invoke Bedrock LLM for root cause analysis (when available) and generate a candidate pattern for human review.
+
+### 4.2 Decision Engine
+
+#### REQ-08-004: Three-Tier Confidence Thresholds
+The system SHALL apply the following decision logic:
+- Confidence >= 0.7 AND auto_healable = true: auto-remediate immediately
+- Confidence >= 0.7 AND auto_healable = false: suggest fix, require approval
+- Confidence 0.3-0.7: suggest fix, require approval
+- Confidence < 0.3: escalate with full diagnostic context
+
+#### REQ-08-005: Rate Limiting
+The system SHALL enforce a maximum of 5 self-heal actions per hour (configurable) and a 10-minute cooldown between identical actions on the same target.
+
+#### REQ-08-006: Cascading Failure Prevention
+The system SHALL limit remediation retries to a maximum of 3 per pattern per incident and implement circuit breaker protection (fail fast after 5 failures in 1 minute).
+
+### 4.3 Remediation
+
+#### REQ-08-007: Remediation Actions
+The system SHALL support the following remediation actions: restart service, scale up replicas, clear cache, rollback deployment, apply configuration fix, and update dependency.
+
+#### REQ-08-008: Approval Requirement for Infrastructure Actions
+Deployment rollbacks, infrastructure scaling, and database failover actions SHALL always require explicit human approval regardless of confidence score.
+
+### 4.4 Feedback Loop
+
+#### REQ-08-009: Confidence Adjustment
+The system SHALL adjust pattern confidence after each remediation attempt: +0.05 for success (maximum 1.0), -0.1 for failure.
+
+#### REQ-08-010: Cross-Project Learning
+Patterns learned in one project SHALL be available to all projects in the knowledge base, enabling cross-project remediation benefit.
+
+### 4.5 Audit and Compliance
+
+#### REQ-08-011: Append-Only Audit Trail
+All self-healing events (auto-remediation, suggestions, escalations) SHALL be recorded in the append-only audit trail with pattern_id, confidence, action_taken, and result, satisfying NIST IR-4, IR-5, and SI-5.
+
+#### REQ-08-012: Rate Limit State Tracking
+The system SHALL track rate limit state in the `self_healing_events` table to enforce per-hour and per-target cooldown limits across process restarts.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `knowledge_patterns` | Failure pattern signatures with root cause, remediation, confidence, and use count |
+| `self_healing_events` | Append-only record of all self-healing actions (auto, suggested, escalated) |
+| `metric_snapshots` | Time-series metric data feeding anomaly detection |
+| `alerts` | Correlated alerts with severity roll-up and root cause grouping |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/knowledge/pattern_detector.py` | Match detected anomalies against knowledge base using BM25 + statistical methods |
+| `tools/knowledge/self_heal_analyzer.py` | Root cause analysis (pattern-based or Bedrock LLM), remediation execution |
+| `tools/knowledge/recommendation_engine.py` | Generate recommendations for unmatched patterns |
+| `tools/monitor/log_analyzer.py` | Parse logs for error patterns, anomalies, and security events |
+| `tools/monitor/metric_collector.py` | Collect metrics from Prometheus/Grafana endpoints |
+| `tools/monitor/alert_correlator.py` | Correlate related alerts into single root cause groups |
+| `tools/audit/audit_logger.py` | Record self-healing events in append-only audit trail |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D4 | Statistical methods for pattern detection; Bedrock LLM for root cause analysis | GPU not available in environment; statistical methods are deterministic and air-gap safe; LLM supplements for unknown patterns only |
+| D146 | Application-level circuit breaker using ABC + in-memory state (stdlib only) | Prevents cascading remediation failures; 3-state machine (CLOSED, OPEN, HALF_OPEN) matches the self-healing retry pattern |
+| D147 | Reusable retry utility with exponential backoff + full jitter | Self-healing actions need configurable retry with backoff; extracted from bedrock_client.py for reuse |
+
+---
+
+## 8. Security Gate
+
+**Self-Healing Gate:**
+- Maximum 5 auto-heal actions per hour enforced
+- 10-minute cooldown between identical actions on same target
+- Maximum 3 retries per pattern per incident
+- Infrastructure actions (rollback, scale, failover) require explicit human approval regardless of confidence
+- All events recorded in append-only audit trail (NIST IR-4, IR-5, SI-5)
+- Unknown patterns (confidence < 0.3) always escalated, never auto-remediated
+
+---
+
+## 9. Commands
+
+```bash
+# Knowledge base pattern detection
+python tools/knowledge/pattern_detector.py --log-data "/path/to/logs"
+
+# Self-healing analysis and remediation
+python tools/knowledge/self_heal_analyzer.py --failure-id "fail-123"
+
+# Recommendation engine
+python tools/knowledge/recommendation_engine.py --project-id "proj-123"
+
+# Monitoring triggers for self-healing
+python tools/monitor/log_analyzer.py --source elk --query "error"
+python tools/monitor/health_checker.py --target "http://service:8080/health"
+
+# Audit trail for self-healing events
+python tools/audit/audit_logger.py --event-type "self_heal.auto" --actor "knowledge-agent" --action "Restarted service X" --project-id "proj-123"
+```
+
+**CUI // SP-CTI**