Security auditor

​

When to use

• Evaluate the security posture of a specification repository
• Prepare for compliance audits (SOC2, GDPR, ISO 27001)
• Validate that security requirements cover the full threat surface
• Review security-related specs after major changes
• Assess security test coverage of specifications
• Verify traceability of security decisions (REQ→INV→ADR→BDD)

​

Invocation

/sdd:security-auditor

​

Core principles

​

1. Threat-driven analysis

❌ "La seguridad podría mejorarse"
❌ "Se recomienda agregar validación"
❌ "Buena práctica es usar X"

✅ "Amenaza: {atacante} puede {acción} porque {gap en spec}"
✅ "No hay mitigación especificada para {amenaza}"
✅ "Pregunta: ¿Qué debe ocurrir cuando {escenario de ataque}?"

​

2. Evidence-based findings

• OWASP ASVS v4 reference (section)
• CWE reference (ID)
• Concrete threat that exploits the gap
• Evidence from 2+ documents

​

3. No implementation, no assumptions

❌ "Se debería implementar WAF"
❌ "Usar AES-256-GCM para esto"
❌ "Agregar este middleware"

✅ "No está especificado el algoritmo de encriptación para {campo}"
✅ "Falta especificar el mecanismo de rate limiting para {endpoint}"
✅ "Pregunta: ¿Qué controles mitigan {amenaza} en {superficie}?"

​

Security defect categories

​

SEC-CAT-01: Amenazas sin modelo (THR-)

• Exposed endpoints without threat analysis
• Data flows without sensitivity classification
• External integrations without trust boundary
• Actors without threat profile

​

SEC-CAT-02: Autenticación incompleta (AUTH-)

• Endpoints without authentication requirement
• Login flows without brute force protection
• Incomplete token management (refresh, revocation, blacklist)
• MFA without recovery specification
• Session management without timeout/invalidation

​

SEC-CAT-03: Autorización insuficiente (AUTHZ-)

• Endpoints without permission in PERMISSIONS-MATRIX
• Operations without tenant isolation verification
• Privilege escalation not covered
• Incomplete RBAC (roles without operation scope)
• Row-level security not specified

​

SEC-CAT-04: Datos sin protección (DATA-)

• PII fields without encryption marker
• Sensitive data in logs or error messages
• Data in transit without TLS specified
• Data at rest without encryption policy
• Data shared between tenants without isolation

​

SEC-CAT-05: Validación de entrada ausente (INPUT-)

• User inputs without validation schema
• File uploads without type/size restriction
• URL parameters without sanitization
• Queries without injection protection
• Free text fields without length limit

​

SEC-CAT-06: Criptografía débil o incompleta (CRYPTO-)

• Algorithms not specified or deprecated
• Key management without lifecycle (generation, rotation, destruction)
• IV/nonce reuse not prevented
• Key derivation without specification
• Encryption without integrity (confidentiality without authentication)

​

SEC-CAT-07: Respuesta a incidentes incompleta (INCIDENT-)

• Security events without taxonomy
• Alerts without threshold or escalation
• Incidents without runbook
• Logs without retention specified
• Incomplete audit trail

​

SEC-CAT-08: Compliance regulatorio incompleto (COMPLY-)

• GDPR rights without UC or mechanism
• Consent without collection/revocation specification
• Data retention without policy or enforcement
• Cross-border data transfer without justification
• DPO/DPA without reference

​

SEC-CAT-09: Tests de seguridad ausentes (STEST-)

• Security requirements without BDD scenario
• Authorization flows without negative test
• Input validation without property tests
• Encryption without correctness test
• GDPR flows without compliance test

​

SEC-CAT-10: Decisiones de seguridad sin ADR (SADR-)

• Cryptographic algorithms chosen without ADR
• Auth strategy without ADR
• Trust boundaries without justification
• Undocumented security trade-offs

​

Security Posture Scorecard

​

10 dimensions

​

Score formula

Score(D) = max(0, 100 - (critical_findings * 25) - (high_findings * 15) - (medium_findings * 5) - (low_findings * 2))

Global = Σ (Score(Di) * Weight(Di))

​

Grades

​

Audit process

​

Phase 0: Security baseline loading

1. Search for SECURITY-AUDIT-BASELINE.md in audits directory
2. If baseline exists:
   • Load all findings with status accepted, wont_fix, or deferred
   • Exclude these findings from report (NOT re-reported)
   • Track in “Excluded by Baseline” counter
   • For deferred findings: check Re-evaluar en date — if past due, re-report
3. If no baseline: proceed normally (first security audit)
4. Load previous security audit report to classify findings as new, persistent, or regression

​

Phase 1: Security spec inventory

1. Core security docs: nfr/SECURITY.md, contracts/PERMISSIONS-MATRIX.md, security ADRs, security runbooks
2. Security-touching docs: All API contracts (auth per endpoint), all UCs with authorization/PII, domain model (PII fields), BDD tests with security scenarios, REQ-SEC
3. Output: Complete security spec inventory with document count and coverage assessment

​

Phase 2: Threat surface mapping

1. API surface: List all endpoints, classify (public/authenticated/admin-only), map auth requirements
2. Data surface: List all PII fields, map encryption requirements, identify data flows
3. Integration surface: External services (LLM APIs, OAuth, SSO), worker-to-worker, file upload/download
4. Trust boundaries: Client→API, API→Storage, Worker→Worker, API→External

​

Phase 3: Coverage analysis

1. Authentication: Every endpoint has auth? Token lifecycle? MFA for sensitive ops?
2. Authorization: Every endpoint has role? Tenant isolation? Row-level security?
3. Data protection: Every PII field encrypted? Key rotation? Data retention?
4. Input validation: Every UC input has schema? File upload restrictions? API param validation?

​

Phase 4: Depth analysis

1. SECURITY.md depth: Auth (method, hash, session, refresh, MFA, lockout), Authz (RBAC, matrix ref, tenant isolation), Crypto (algorithms, key mgmt, rotation, IV), Audit (events, retention, format), Incident (detection, response, recovery)
2. PERMISSIONS-MATRIX depth: Every role has permissions, every endpoint in matrix, deny-by-default, scope qualifiers
3. Security ADRs depth: Context explains threat, decision specifies control, alternatives considered, consequences include trade-offs
4. Runbooks depth: Pre-requisites, step-by-step with verification, rollback, communication plan

​

Phase 5: Traceability verification

REQ-SEC → INV-SEC/INV-PII → ADR → UC (security flow) → BDD (security scenario) → Runbook

1. Forward trace: Each REQ-SEC → has INV or ADR → has UC flow → has BDD test
2. Backward trace: Each security BDD → maps to UC → maps to REQ-SEC
3. Gap detection: REQ-SEC without test, INV without enforcement, ADR without runbook

​

Phase 6: Security Posture Scorecard

1. Count findings per dimension (each SEC-CAT maps to a dimension)
2. Calculate score per dimension using the formula
3. Calculate global score as weighted average
4. Assign grade (A-F)
5. Highlight weakest dimensions for priority remediation

​

Phase 7: Report generation

• Security Posture Scorecard (10 dimensions with grades)
• Executive Summary (findings by category)
• Baseline Delta (new/persistent/regression findings)
• Threat Surface Summary (API/PII/Integrations/Boundaries coverage)
• Traceability Summary (REQ-SEC chains completeness)
• Findings by Category (10 SEC-CATs with detailed findings)
• Findings Excluded by Baseline (count and breakdown)
• Prioritization Recommendations (by severity)

​

Finding format

#### {PREFIX}-{NNN}: {Título}

| Campo | Valor |
|-------|-------|
| **Severidad** | Crítico / Alto / Medio / Bajo |
| **Estado** | new / persistent / regression |
| **Categoría** | SEC-CAT-{NN}: {nombre} |
| **OWASP ASVS** | V{N}.{N} |
| **CWE** | CWE-{NNN} |
| **Ubicación** | {documento}:{sección} |
| **Amenaza** | {qué podría salir mal} |
| **Problema** | {descripción del defecto en la spec} |
| **Pregunta** | {pregunta para resolver el gap} |
| **Docs relacionados** | {lista} |
| **Mitigación existente** | {parcial si aplica, o "ninguna"} |

​

Severity classification

​

Signal filters

1. Threat requirement: Only report findings with concrete threat scenario
2. Evidence from 2+ docs: Cross-reference required
3. Respect security ADRs: If documented in ADR with trade-off analysis, NOT a defect
4. Respect existing mitigations: Partial mitigation = Medium (not Critical)
5. Implementation-blocking test: Does this gap block safe implementation?

​

Constraints

• Never propose implementation: Only identify gap and formulate question
• Never assume behavior: If not specified, it’s a finding
• Always include OWASP/CWE reference: Every finding with standard classification
• Always indicate concrete threat: Not “could be insecure” but “attacker can X”
• Always cross-reference documents: Minimum 2 docs per finding
• Always generate scorecard: Even if 0 findings, report all 10 dimensions
• Never duplicate with spec-auditor: Only findings with demonstrable security impact

​

Related skills