Skyclaw Purple Team Auditor v2.1

❌ Cuándo NO Usar

• Formateo o refactorización de código sin requisitos de seguridad
• Análisis de código de terceros sin acceso al fuente completo
• Cuando se requiere ejecución dinámica sin sandbox
• Problemas de performance no relacionados con seguridad

🏗️ Arquitectura de Auditoría

SKYCLAW PURPLE AUDITOR CYCLE v2.1 │
│ (7-Phase Metacognitive + AST Analysis) 
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 1: CONTEXTUAL ANALYSIS                                         │
│  - Mapeo de trust boundaries                                         │
│  - Identificación de activos críticos                                │
│  - Evaluación de riesgo inicial                                      │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 2: DECOMPOSITION                                               │
│  - División por módulos/componentes                                  │
│  - Grafo de dependencias                                             │
│  - Identificación de puntos de entrada/salida                        │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 3: RESOLUTION (AST + Vector Match)                             │
│  ┌────────────────────┐    ┌────────────────────┐                    │
│  │  AST Guardian      │    │  Vector Store      │                    │
│  │  - Parseo Python   │    │  - Patrones CWE    │                    │
│  │  - Grafo de flujo  │    │  - Data flow       │                    │
│  │  - Data flow       │    │  - Historical hits │                    │
│  └────────────────────┘    └────────────────────┘                    │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 4: VERIFICATION (5 Layers)                                     │
│  - Logical: Consistencia de hallazgos                                │
│  - Factual: Validación contra CVE/CWE database                       │
│  - Completeness: Cobertura de reglas OWASP                           │
│  - Bias: Falsos positivos/negativos                                  │
│  - Security: PII/secret detection en hallazgos                       │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 5: SYNTHESIS                                                   │
│  - Agregación ponderada de hallazgos                                 │
│  - Confidence scoring por vulnerabilidad                             │
│  - Priorización por riesgo (CVSS 4.0)                                │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 6: REFLECTION + HITL DECISION                                  │
│  - ¿Confianza ≥ 0.85? → Accept                                       │
│  - ¿Confianza 0.70-0.85? → Iterate                                   │
│  - ¿Confianza < 0.70 o CRITICAL? → HITL Escalation                   │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  FASE 7: DOCUMENTATION (SARIF + Audit Trail)                         │
│  - Export SARIF v2.1 para SIEM                                       │
│  - Audit trail inmutable en SQLite (WAL mode)                        │
│  - Knowledge artifact para aprendizaje futuro                        │
└──────────────────────────────────────────────────────────────────────┘

🔧 Instrucciones de Ejecución

1. Inicialización de Auditoría

# Inicializar auditor con configuración de soberanía local
auditor = SkyclawPurpleAuditor(
    execution_mode="local_wsl2",
    sandbox_profile="gvisor_strict",
    vector_store="qdrant_local",
    enable_hitl=True,
    compliance_frameworks=["NIST_CSF_2.0", "ISO_27001", "EU_AI_ACT"]
)

# Ejecutar auditoría
result = await auditor.audit(
    target_path="/path/to/code",
    audit_type="comprehensive",  # o "quick", "compliance", "pre-deployment"
    context={
        "risk_level": "high",
        "data_sensitivity": "pii",
        "external_integrations": True
    }
)

Ejecución del AST Guardian (Sandboxed)

# CRÍTICO: Todo análisis dinámico debe ejecutarse en sandbox
bash scripts/wsl_sandbox_exec.sh python3 scripts/ast_guardian.py \
    --target <FILE_PATH> \
    --output-format sarif \
    --vector-match-enabled \
    --confidence-threshold 0.75 \
    --audit-session-id <UUID>

Integración con Vector Store Local

# Búsqueda de patrones de vulnerabilidad en vector store
vulnerability_patterns = await auditor.vector_store.semantic_search(
    query="SQL injection user input concatenation",
    top_k=10,
    filters={"cwe_id": ["CWE-89", "CWE-94"], "severity": ["high", "critical"]}
)

# Match contra código analizado
matches = await auditor.pattern_matcher.find_matches(
    ast_graph=code_ast,
    patterns=vulnerability_patterns,
    confidence_threshold=0.80
)

HITL Escalation para Hallazgos Críticos

# Triggers automáticos de HITL
hitl_triggers:
  severity: ["critical", "high"]
  cwe_ids: ["CWE-94", "CWE-89", "CWE-78", "CWE-287"]
  data_exfiltration_risk: true
  credential_exposure: true
  rce_potential: true
  compliance_violation: true

# Cuando se activa, pausa y espera aprobación humana
if hitl_triggered:
    await auditor.human_approval_gateway.request_approval(
        session_id=audit_session_id,
        findings=critical_findings,
        recommended_actions=["block_deployment", "require_remediation"],
        timeout_minutes=60
    )

Reglas de Seguridad (Trail of Bits First Principles)

Trust Boundary Mapping

# Identificar fronteras de confianza antes de análisis
trust_boundaries = {
    "external_input": ["API endpoints", "user input", "file uploads", "env vars"],
    "internal_trusted": ["core modules", "validated functions", "sandboxed code"],
    "external_output": ["network calls", "file writes", "logs", "database"]
}

# Regla: Todo dato cruzando frontera debe ser validado/sanitizado
for boundary_crossing in identify_boundary_crossings(ast_graph):
    if not has_validation(boundary_crossing):
        flag_vulnerability("TRUST_BOUNDARY_VIOLATION")

Whys/Hows Analysis

# Para cada hallazgo crítico, aplicar 5 Whys
def root_cause_analysis(finding):
    why_chain = []
    current_why = finding.description
    
    for i in range(5):
        why = ask_why(current_why)
        why_chain.append(why)
        current_why = why
        
        if is_root_cause(why):
            break
    
    return {
        "finding": finding,
        "why_chain": why_chain,
        "root_cause": why_chain[-1],
        "systemic_fix": recommend_systemic_fix(why_chain)
    }

Formato de Salida de Hallazgos

Métricas de Calidad de Auditoría

🔗 Integración con Sky-Claw Ecosystem

Metacognitive Framework Integration

# La auditoría usa el framework metacognitivo de 7 fases
from src.metacognitive_framework import MetacognitiveReasoningFramework

class SkyclawPurpleAuditor:
    def __init__(self, config: AuditConfig):
        self.config = config
        self.metacognitive_framework = MetacognitiveReasoningFramework(
            domain="security_audit",
            execution_mode=config.execution_mode,
            enable_hitl=config.enable_hitl
        )
        self.vector_store = config.vector_store
        self.ast_guardian = ASTGuardian(sandbox=config.sandbox_profile)
    
    async def audit(self, target_path: str, context: Dict) -> AuditResult:
        # Ejecutar ciclo metacognitivo completo
        result = await self.metacognitive_framework.execute(
            problem=f"Auditar seguridad de {target_path}",
            context={
                **context,
                "audit_type": "security",
                "target_path": target_path,
                "compliance_frameworks": self.config.compliance_frameworks
            }
        )
        return AuditResult.from_metacognitive_result(result)

SQLite Audit Trail (WAL Mode)

# Registro silente en base de datos local
async def persist_audit_finding(self, finding: AuditFinding) -> None:
    """
    Persiste hallazgo en SQLite con WAL mode para concurrencia.
    Los registros son INMUTABLES una vez creados.
    """
    async with self.db_manager.get_thread_local_connection() as conn:
        await conn.execute("PRAGMA journal_mode=WAL;")
        await conn.execute("PRAGMA foreign_keys=ON;")
        
        async with conn.transaction():  # BEGIN IMMEDIATE / COMMIT
            await conn.execute("""
                INSERT INTO audit_findings (
                    session_id, finding_id, severity, cwe_id, nist_control,
                    confidence, file_path, line_number, status, created_at
                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            """, (
                self.session_id,
                finding.id,
                finding.severity.value,
                finding.cwe_id,
                finding.nist_control,
                finding.confidence,
                finding.file_path,
                finding.line_number,
                "open",
                datetime.now(timezone.utc).isoformat()
            ))

Restricciones Críticas

🧪 Ejemplo de Sesión Completa

{
  "audit_session_id": "a7f3c890-1234-5678-9abc-def012345678",
  "target_path": "/home/skyclaw/projects/sky-claw/src/",
  "audit_type": "comprehensive",
  "start_time": "2026-03-29T14:00:00Z",
  "end_time": "2026-03-29T14:03:45Z",
  "duration_seconds": 225,
  "lines_of_code_analyzed": 15420,
  "findings_summary": {
    "critical": 1,
    "high": 3,
    "medium": 7,
    "low": 12,
    "total": 23
  },
  "confidence_metrics": {
    "average": 0.87,
    "min": 0.72,
    "max": 0.96,
    "brier_score": 0.08
  },
  "hitl_triggered": true,
  "hitl_findings": ["VULN-001", "VULN-002"],
  "hitl_approved": true,
  "compliance_mapping": {
    "NIST_CSF_2.0": {
      "Identify": 5,
      "Protect": 8,
      "Detect": 6,
      "Respond": 3,
      "Recover": 1
    },
    "ISO_27001": {
      "A.9": 4,
      "A.12": 7,
      "A.14": 5,
      "A.18": 7
    }
  },
  "sarif_export_path": "~/.sky_claw/audits/sarif_2026-03-29_a7f3c890.sarif",
  "audit_trail_path": "~/.sky_claw/audits/sqlite/audit_2026-03-29.db",
  "phases_completed": [
    "contextual_analysis",
    "decomposition",
    "resolution",
    "verification",
    "synthesis",
    "reflection",
    "documentation"
  ],
  "iterations": 1,
  "final_confidence": 0.89
}

Estructura de Archivos

.agents/skills/skyclaw-purple-auditor/
├── SKILL.md                          # Este archivo
├── src/
│   ├── purple_auditor.py             # Clase principal
│   ├── ast_guardian.py               # Análisis estático
│   ├── pattern_matcher.py            # Vector-based pattern matching
│   └── hitl_gateway.py               # Human-in-the-loop gateway
├── scripts/
│   ├── wsl_sandbox_exec.sh           # Sandbox execution wrapper
│   ├── ast_guardian.py               # AST analysis script
│   └── export_sarif.py               # SARIF export utility
├── resources/
│   ├── vulnerability_patterns.json   # Patrones CWE/OWASP
│   ├── nist_controls.toml            # Mapeo NIST CSF 2.0
│   ├── iso27001_controls.toml        # Mapeo ISO 27001
│   └── audit_schema.json             # Schema de audit trail
├── examples/
│   └── sample_audit_result.json      # Ejemplo de resultado
└── tests/
    ├── test_purple_auditor.py        # Tests unitarios
    ├── test_ast_guardian.py          # Tests AST
    └── conftest.py                   # Fixtures pytest

Comandos Rápidos

# Auditoría rápida (solo AST, sin vector match)
bash scripts/wsl_sandbox_exec.sh python3 scripts/ast_guardian.py \
    --target ./src/ --mode quick

# Auditoría completa (AST + Vector + Compliance)
bash scripts/wsl_sandbox_exec.sh python3 scripts/ast_guardian.py \
    --target ./src/ --mode comprehensive --compliance NIST,ISO

# Exportar resultados a SARIF
python3 scripts/export_sarif.py --session <SESSION_ID> --output ./results.sarif

# Validar salud del auditor
python3 scripts/validate_auditor.py --health-check

# Recalibrar confianza con datos históricos
python3 scripts/calibrate_confidence.py --historical-data ./audits/

Referencias de Estándares

⚠️ Advertencias Críticas

• No usar en producción sin calibración - Ejecutar al menos 30 auditorías de calibración antes de deployment
• WSL2 requiere configuración de sandbox - gVisor/AppArmor deben estar habilitados
• HITL timeout es configurable - Default 60 minutos para hallazgos críticos
• Audit trails son inmutables - No modificar registros completados (compliance requirement)
• Confianza no es certeza - Validar hallazgos críticos con penetration testing

🎯 Score de la Skill