diff --git a/skills/NOTICE.md b/skills/NOTICE.md index 0d3b523..cb66147 100644 --- a/skills/NOTICE.md +++ b/skills/NOTICE.md @@ -25,8 +25,52 @@ repo de origem, ou comparar datas). Licença CC-BY-4.0 (OWASP/secure-agent-playbook) exige atribuição — mantida via a tabela acima e o link direto ao repo original em cada menção nos READMEs. Nenhum conteúdo foi modificado em relação ao original; cópia 1:1 -do diretório da skill (mais `check_deps.py` no caso do `safedeps`, que a -skill referencia como script auxiliar). +do diretório da skill, mais os arquivos de apoio que a própria skill +referencia (ver abaixo). + +## Arquivos de apoio vendorizados + +Os `SKILL.md` acima não são autossuficientes: eles apontam para playbooks, +templates e schemas que ficam em outros diretórios do repo de origem. A +primeira vendorização copiou só o `SKILL.md` e deixou esses arquivos para +trás — o resultado é que a skill carregava e apontava para um arquivo +inexistente. Eles foram trazidos junto, dentro do diretório de cada skill, +para que ela continue funcional depois de copiada sozinha: + +| Arquivo | Skill(s) que referenciam | Origem | +|---|---|---| +| `plays/api-security-review.md` | `api-security-review` | OWASP/secure-agent-playbook `plugins/code-security-skills/plays/` | +| `plays/code-review-security.md` | `code-review-security` | idem | +| `plays/sca-audit.md` | `sca-audit` | idem | +| `plays/secrets-scan.md` | `secrets-scan` | idem | +| `plays/owasp-top10-web-review.md` | `web-security-review` | idem | +| `templates/finding.md` | `code-review-security`, `sca-audit`, `secrets-scan`, `web-security-review` | idem, `templates/` | +| `schemas/finding.schema.json` | `cve-triage`, `patch-prioritization`, `dependency-scanning` | UnitOneAI/SecuritySkills `schemas/` | +| `docs/sarif-output.md` | `dependency-scanning` | UnitOneAI/SecuritySkills `docs/` | +| `docs/fixer-policy.md` | `dependency-scanning` | UnitOneAI/SecuritySkills `docs/` | +| `docs/normalized-json-output.md` | `dependency-scanning` (linkado de `docs/sarif-output.md`) | UnitOneAI/SecuritySkills `docs/` | + +Esses arquivos são cópias 1:1 do upstream. A única edição nos `SKILL.md` foi +nos caminhos: as referências `../../../schemas/…` e `../../../docs/…` +apontavam para a raiz do repo de origem, que tinha um nível a mais +(`skills///`). Como aqui o diretório é plano +(`skills//`), os links foram ajustados para o caminho relativo dentro +da própria skill, que é o que sobrevive a `cp -r skills/* ~/.hermes/skills/`. + +## Lacunas conhecidas + +- `hermaguard` referencia `governance/multi-gate-qa.md` e + `.github/workflows/hermaguard.yml`, que existem só no ambiente do autor + original (pipeline `kensei`), não no repo upstream. Não foram criados: são + contexto de integração, não dependência de execução da skill. +- Os playbooks citam controles ASVS em `data/asvs/*.md` (dataset do + OWASP/secure-agent-playbook). São citações informativas por check, não + arquivos que a skill precise abrir para rodar; o dataset inteiro (~90 + arquivos) não foi vendorizado de propósito. +- `hermaguard` foi vendorizado no commit `b491fbe`; o upstream já avançou + (adicionou a ferramenta `hermaguard-trajectory` e `test_trajectory.py`). A + cópia local é internamente consistente (README, `pyproject.toml` e testes + batem entre si), mas está atrás do upstream. Pra atualizar uma skill vendorizada: reclone o repo de origem, `diff -r` contra o diretório aqui, copie por cima se houver mudança real, e atualize diff --git a/skills/api-security-review/plays/api-security-review.md b/skills/api-security-review/plays/api-security-review.md new file mode 100644 index 0000000..335958b --- /dev/null +++ b/skills/api-security-review/plays/api-security-review.md @@ -0,0 +1,1506 @@ +# Play: API Security Review + +Comprehensive API security assessment against OWASP API Security Top 10 (2023) with real-world attack scenarios, automated testing integration, and detailed remediation guidance. + +## Trigger Conditions + +Use this play when: +- Reviewing OpenAPI/Swagger specifications or API documentation +- Auditing REST, GraphQL, gRPC, or SOAP API implementations +- Testing API authentication and authorization mechanisms +- Reviewing API gateway configurations (Kong, nginx, Envoy, AWS API Gateway) +- Conducting pre-deployment security assessments +- Performing API penetration testing or security audits +- A user asks to "test my API for security issues" + +## Inputs + +- OpenAPI/Swagger specification (YAML/JSON) or API documentation +- API source code (routes, controllers, middleware, authentication logic) +- API gateway and infrastructure configurations +- Authentication implementation details (JWT, OAuth, API keys) +- Environment information (production, staging, development) +- Previous security assessment reports (if available) + +## Procedure + +### Phase 1: Discovery & Reconnaissance + +#### 1.1 API Surface Enumeration + +**With OpenAPI Spec:** +```bash +# Parse and analyze OpenAPI spec +# Look for: +- Total endpoints and HTTP methods +- Authentication requirements per endpoint +- Request/response schemas +- Rate limiting documentation +- Deprecated endpoints +``` + +**Without OpenAPI Spec (Code Analysis):** +- Scan route definitions in framework-specific patterns: + - Express: `app.get()`, `router.post()` + - Django: `path()`, `url()` + - Rails: `resources`, `get/post/put/delete` + - Spring: `@GetMapping`, `@RequestMapping` + - FastAPI: `@app.get()`, decorator-based routes + +**Key Questions:** +- How many endpoints exist? +- Which require authentication vs. public? +- What data types are exchanged? +- Are there file upload endpoints? +- Are there admin/debug endpoints? + +#### 1.2 Authentication Mechanism Identification + +Document all auth mechanisms in use: + +| Mechanism | Indicators | Security Considerations | +|-----------|-----------|------------------------| +| **JWT** | `Authorization: Bearer eyJ...` | Algorithm, signing key strength, expiration | +| **OAuth 2.0** | `/oauth/authorize`, `/oauth/token` | Flow type, PKCE, state parameter, redirect URI | +| **API Keys** | `X-API-Key`, `api_key` query param | Key rotation, transmission security, scope | +| **Session Cookies** | `Set-Cookie: sessionid=...` | HttpOnly, Secure, SameSite, expiration | +| **mTLS** | Client certificate requirements | Certificate validation, revocation | +| **Basic Auth** | `Authorization: Basic base64` | HTTPS enforcement, credential storage | + +### Phase 2: Authentication Security Assessment + +#### 2.1 JWT Security Testing + +**Common JWT Vulnerabilities:** + +1. **Algorithm Confusion (CVE-2015-9235)** + ``` + Attack: Change algorithm from RS256 to none or HS256 + Header: {"alg":"none","typ":"JWT"} + Result: Token accepted without verification + ``` + +2. **Weak Signing Keys** + ```bash + # Test for weak secrets if using HS256 + # Use jwt_tool or hashcat for brute force + jwt_tool.py token_here -C -d /usr/share/wordlists/rockyou.txt + ``` + +3. **Missing Expiration** + ``` + Check: Does payload contain "exp" claim? + Risk: Tokens valid forever if stolen + ``` + +4. **Token Storage Issues** + ```javascript + // Insecure: localStorage (XSS accessible) + localStorage.setItem('jwt', token); + + // More secure: httpOnly cookie + document.cookie = "jwt=" + token + "; HttpOnly; Secure; SameSite=Strict"; + ``` + +**Testing Checklist:** +- [ ] Test algorithm confusion (change alg to "none") +- [ ] Attempt key confusion attacks (RS256 → HS256) +- [ ] Check for missing expiration (exp claim) +- [ ] Verify signature validation cannot be bypassed +- [ ] Test token revocation mechanisms +- [ ] Check for sensitive data in JWT payload + +#### 2.2 OAuth 2.0 Security Testing + +**Critical Checks:** + +1. **Authorization Code Flow** + ``` + Required: PKCE (Proof Key for Code Exchange) + Check: code_challenge and code_verifier parameters + Risk: Without PKCE, auth codes can be stolen and used + ``` + +2. **State Parameter** + ``` + Required: Random state parameter to prevent CSRF + Check: Is state validated on callback? + Attack: Omit state → CSRF login attack + ``` + +3. **Redirect URI Validation** + ``` + Check: Is redirect_uri strictly validated? + Attack: redirect_uri=https://attacker.com/callback + Risk: Authorization code/token sent to attacker + ``` + +4. **Scope Validation** + ``` + Check: Can user modify requested scopes? + Attack: Change scope=read to scope=admin + Risk: Privilege escalation via scope manipulation + ``` + +**Testing Checklist:** +- [ ] Verify PKCE implementation for public clients +- [ ] Test state parameter CSRF protection +- [ ] Attempt redirect URI manipulation +- [ ] Test scope escalation attacks +- [ ] Check for open redirect vulnerabilities +- [ ] Verify token endpoint authentication + +#### 2.3 API Key Security + +**Common Issues:** + +1. **Key Exposure** + ```bash + # Search for hardcoded keys + grep -r "api_key\|apikey\|api-key" --include="*.js" --include="*.py" --include="*.env" + + # Check client-side code + # API keys in frontend code can be stolen + ``` + +2. **Insufficient Scope** + ``` + Issue: Single key with full access + Best Practice: Scoped keys (read-only, write, admin) + ``` + +3. **Missing Rotation** + ``` + Check: Can keys be rotated without downtime? + Risk: Compromised keys valid indefinitely + ``` + +### Phase 3: OWASP API Top 10 Deep Assessment + +#### API1: Broken Object Level Authorization (BOLA/IDOR) + +> **Risk**: Attackers access other users' data by manipulating object IDs + +**Real-World Impact**: +- **2019**: First American Financial exposed 885 million records via IDOR +- **2020**: Twitter API IDOR allowed viewing protected tweets +- **2021**: Facebook IDOR exposed private posts + +**Attack Scenarios:** + +1. **Sequential ID Manipulation** + ```http + GET /api/users/123/orders + + # Try: + GET /api/users/124/orders # Access other user's orders + GET /api/users/1/orders # Access admin's orders + ``` + +2. **UUID Predictability** + ``` + If using predictable UUIDv1 (timestamp-based): + Generate nearby UUIDs to find other users + ``` + +3. **Batch Endpoint Bypass** + ```http + POST /api/orders/bulk + { + "order_ids": [1001, 1002, 1003, 1004] # Can access any IDs? + } + ``` + +4. **Indirect Object References** + ```http + GET /api/orders?id=1001 + + # vs + + GET /api/orders?id=1001&user_id=123 # Is user_id validated? + ``` + +**Testing Approach:** + +1. **Map Object IDs**: Identify all endpoints accepting object IDs +2. **Cross-User Testing**: + - Create User A and User B accounts + - Have User A create resources + - Attempt to access with User B's credentials +3. **Batch Testing**: Test if batch endpoints filter by ownership +4. **File Access**: Test file download endpoints with different IDs +5. **IDOR Automation**: + ```bash + # Use Burp Intruder or custom script + # Iterate through IDs and check for 200 responses + for i in {1..1000}; do + curl -H "Authorization: Bearer $TOKEN" \ + "https://api.example.com/orders/$i" | grep -q "order_id" && echo "Found: $i" + done + ``` + +**Remediation:** +```python +# BAD: No ownership check +def get_order(order_id): + return Order.objects.get(id=order_id) + +# GOOD: Verify ownership +def get_order(order_id, user): + return Order.objects.get(id=order_id, user=user) + # Or: Check ownership after retrieval + order = Order.objects.get(id=order_id) + if order.user_id != user.id: + raise PermissionDenied() + return order +``` + +#### API2: Broken Authentication + +> **Risk**: Weak authentication allows account takeover + +**Real-World Impact**: +- **2022**: Uber breach via compromised contractor account +- **2023**: 23andMe breach via credential stuffing + +**Attack Scenarios:** + +1. **Credential Stuffing** + ```bash + # Automated login attempts with breached credentials + # APIs often lack CAPTCHA or rate limiting + ``` + +2. **JWT None Algorithm** + ``` + Header: {"alg":"none","typ":"JWT"} + Payload: {"user_id":1,"role":"admin"} + Signature: (empty) + + Result: Server accepts unsigned token + ``` + +3. **Weak Password Policy** + ``` + POST /api/login + {"username":"admin","password":"123456"} + + # Test common passwords + # Check minimum length requirements + ``` + +4. **Session Fixation** + ``` + Attacker sets session ID + Victim logs in with attacker's session ID + Attacker uses same session ID to access account + ``` + +**Testing Approach:** + +1. **Brute Force Testing**: + ```bash + # Test login endpoint rate limiting + for i in {1..100}; do + curl -X POST https://api.example.com/login \ + -d "username=admin&password=wrong$i" + done + # Check if account locks or IP is blocked + ``` + +2. **Token Security**: + - Decode JWT and analyze claims + - Test algorithm confusion + - Check expiration and refresh mechanisms + - Test token revocation + +3. **Password Policy**: + - Test minimum length (should be 12+) + - Test complexity requirements + - Check common password blocking + - Verify secure password reset flow + +4. **Multi-Factor Authentication**: + - Is MFA enforced for sensitive operations? + - Can MFA be bypassed? + - Are backup codes secure? + +**Remediation:** +```python +# Implement rate limiting +from django_ratelimit.decorators import ratelimit + +@ratelimit(key='ip', rate='5/m', method='POST') +def login(request): + # Login logic + pass + +# Strong password validation +from django.contrib.auth.password_validation import validate_password + +def validate_user_password(password): + try: + validate_password(password) + except ValidationError as e: + raise e + +# Secure JWT configuration +JWT_SETTINGS = { + 'ALGORITHM': 'HS256', # Use strong algorithms only + 'VERIFY_EXPIRATION': True, + 'EXPIRATION_DELTA': timedelta(minutes=15), + 'REFRESH_EXPIRATION_DELTA': timedelta(days=7), +} +``` + +#### API3: Broken Object Property Level Authorization + +> **Risk**: Mass assignment and data over-exposure + +**Real-World Impact**: +- **2012**: GitHub mass assignment allowed unauthorized repo access +- **2019**: Facebook mass assignment exposed user data + +**Attack Scenarios:** + +1. **Mass Assignment** + ```http + POST /api/users + { + "username": "newuser", + "email": "user@example.com", + "password": "password123", + "role": "admin", # Should not be user-settable + "is_verified": true # Should not be user-settable + } + ``` + +2. **Response Over-Exposure** + ```http + GET /api/users/123 + + Response: + { + "id": 123, + "username": "john", + "email": "john@example.com", + "password_hash": "$2b$12$...", # Should not be exposed! + "ssn": "123-45-6789", # PII exposure + "internal_notes": "Difficult customer" + } + ``` + +3. **Field-Level Authorization Bypass** + ```http + PUT /api/users/123 + { + "salary": 200000 # Can regular users modify this? + } + ``` + +**Testing Approach:** + +1. **Mass Assignment Testing**: + ```python + # Send extra fields in POST/PUT requests + payload = { + "username": "test", + "email": "test@test.com", + "password": "password", + "role": "admin", # Try to escalate + "is_admin": True, + "credit_balance": 10000 + } + ``` + +2. **Response Analysis**: + - Capture all API responses + - Look for sensitive fields (passwords, tokens, PII) + - Compare responses for different user roles + - Check if internal fields are exposed + +3. **GraphQL Over-Exposure**: + ```graphql + # Request fields you shouldn't see + query { + user(id: 123) { + id + name + email + password # Should be rejected + ssn # Should be rejected + salary # Should be rejected for non-admins + } + } + ``` + +**Remediation:** +```python +# Use allowlist approach +ALLOWED_USER_FIELDS = ['username', 'email', 'password'] + +def update_user(user_id, data, current_user): + # Filter input to allowed fields only + filtered_data = {k: v for k, v in data.items() + if k in ALLOWED_USER_FIELDS} + + # Check field-level permissions + if 'role' in data and not current_user.is_admin: + raise PermissionDenied("Cannot modify role") + + return User.objects.filter(id=user_id).update(**filtered_data) + +# Response serialization +class UserSerializer(serializers.ModelSerializer): + class Meta: + model = User + fields = ['id', 'username', 'email'] # Explicit allowlist + # Never include: password, ssn, internal_notes +``` + +#### API4: Unrestricted Resource Consumption + +> **Risk**: DoS via resource exhaustion, financial drain + +**Real-World Impact**: +- **2023**: OpenAI API abuse cost companies thousands +- **2022**: GraphQL query DoS attacks on multiple platforms + +**Attack Scenarios:** + +1. **Rate Limit Bypass** + ```http + # Distributed attack from multiple IPs + # Or using different API keys + # Or changing User-Agent headers + ``` + +2. **Expensive Query Abuse** + ```graphql + # Deeply nested GraphQL query + query { + users { + posts { + comments { + author { + posts { + comments { + author { + posts { ... } # Infinite recursion potential + } + } + } + } + } + } + } + } + ``` + +3. **Large Payload Attacks** + ```http + POST /api/upload + Content-Length: 1000000000 # 1GB file + + # Or JSON bomb: + {"a":{"a":{"a":{"a":...}}}} # Deeply nested JSON + ``` + +4. **Pagination Abuse** + ```http + GET /api/items?limit=1000000 # Request all records + GET /api/items?page=1&per_page=10000 # Large page size + ``` + +**Testing Approach:** + +1. **Rate Limit Testing**: + ```bash + # Test from single IP + for i in {1..1000}; do + curl https://api.example.com/data + done + + # Test bypass methods: + # - Different API keys + # - Rotating User-Agents + # - Distributed requests + ``` + +2. **GraphQL DoS**: + ```bash + # Test query complexity + # Test query depth + # Test expensive operations + ``` + +3. **Resource Exhaustion**: + - Upload extremely large files + - Send deeply nested JSON + - Request massive result sets + - Trigger expensive database queries + +**Remediation:** +```python +# Rate limiting +from django_ratelimit.decorators import ratelimit + +@ratelimit(key='user', rate='100/h', method=['GET', 'POST']) +def api_endpoint(request): + pass + +# GraphQL safeguards +GRAPHQL_SETTINGS = { + 'MAX_DEPTH': 10, + 'MAX_COMPLEXITY': 1000, + 'DISABLE_INTROSPECTION': True, # In production +} + +# Pagination limits +MAX_PAGE_SIZE = 100 +DEFAULT_PAGE_SIZE = 20 + +def get_items(request): + page_size = min( + int(request.GET.get('limit', DEFAULT_PAGE_SIZE)), + MAX_PAGE_SIZE + ) + return Item.objects.all()[:page_size] + +# File upload limits +MAX_UPLOAD_SIZE = 10 * 1024 * 1024 # 10MB + +# Timeout configuration +REQUEST_TIMEOUT = 30 # seconds +``` + +#### API5: Broken Function Level Authorization + +> **Risk**: Access to admin/sensitive functions without proper authorization + +**Real-World Impact**: +- **2020**: Twitter admin tool breach +- **2021**: Parler admin API exposed + +**Attack Scenarios:** + +1. **Admin Endpoint Discovery** + ```http + GET /api/admin/users # Try common admin paths + GET /api/v1/admin/config + GET /api/internal/audit-logs + GET /api/debug/info + ``` + +2. **HTTP Method Switching** + ```http + GET /api/users/123 # Allowed for regular users + DELETE /api/users/123 # Should require admin, but is it checked? + PUT /api/users/123/role # Can users change their own role? + ``` + +3. **Parameter-Based Access Control** + ```http + POST /api/users + { + "username": "test", + "role": "admin" # Is this validated server-side? + } + ``` + +**Testing Approach:** + +1. **Endpoint Enumeration**: + ```bash + # Use wordlists to find admin endpoints + # Common paths: /admin, /internal, /debug, /system + ``` + +2. **Method Testing**: + ```bash + # For each endpoint, test all HTTP methods + curl -X GET /api/resource + curl -X POST /api/resource + curl -X PUT /api/resource + curl -X DELETE /api/resource + curl -X PATCH /api/resource + ``` + +3. **Role Escalation**: + - Create regular user account + - Attempt to access admin endpoints + - Try to modify role/privilege fields + +**Remediation:** +```python +# Centralized authorization decorator +from functools import wraps + +def require_admin(f): + @wraps(f) + def decorated_function(request, *args, **kwargs): + if not request.user.is_admin: + return Response( + {"error": "Admin access required"}, + status=403 + ) + return f(request, *args, **kwargs) + return decorated_function + +@require_admin +def admin_endpoint(request): + pass + +# Middleware approach +class AdminAuthorizationMiddleware: + def __init__(self, get_response): + self.get_response = get_response + self.admin_paths = ['/api/admin/', '/api/internal/'] + + def __call__(self, request): + if any(request.path.startswith(path) for path in self.admin_paths): + if not request.user.is_admin: + return HttpResponseForbidden() + return self.get_response(request) +``` + +#### API6: Unrestricted Access to Sensitive Business Flows + +> **Risk**: Automated abuse of business logic + +**Real-World Impact**: +- **Ticket scalping**: Bots buying all concert tickets +- **E-commerce**: Inventory hoarding, price scraping +- **Crypto**: Flash loan attacks via API manipulation + +**Attack Scenarios:** + +1. **Inventory Exhaustion** + ```http + POST /api/cart/add + {"product_id": 123, "quantity": 999999} # Buy all inventory + ``` + +2. **Automated Purchasing** + ```http + # Script that completes purchase faster than humans + # Bypassing any client-side rate limits + ``` + +3. **Price Manipulation** + ```http + POST /api/order + { + "items": [...], + "total": 1.00 # Is total calculated server-side? + } + ``` + +4. **Reservation Abuse** + ```http + POST /api/reservations + {"resource_id": 123, "start": "2024-01-01", "end": "2025-12-31"} + # Reserve resource for entire year + ``` + +**Testing Approach:** + +1. **Business Logic Testing**: + - Attempt to complete purchases with modified prices + - Try to add negative quantities + - Test race conditions in multi-step flows + - Attempt to bypass payment steps + +2. **Automation Testing**: + ```python + # Script to test if flows can be automated + import requests + import time + + start = time.time() + for i in range(100): + requests.post('/api/purchase', json={...}) + elapsed = time.time() - start + + # If no rate limiting, 100 requests complete quickly + ``` + +**Remediation:** +```python +# Server-side price calculation +def create_order(items, user): + total = sum(item.product.price * item.quantity for item in items) + # Never trust client-provided total + + # Inventory checks + for item in items: + if item.quantity > item.product.available_stock: + raise ValidationError("Insufficient inventory") + + # Rate limiting per user + if user.orders.filter(created_at__gte=timezone.now() - timedelta(hours=1)).count() > 10: + raise RateLimitError("Too many orders") + + return Order.objects.create(user=user, items=items, total=total) + +# CAPTCHA for sensitive operations +from django_recaptcha.fields import ReCaptchaField + +class PurchaseForm(forms.Form): + recaptcha = ReCaptchaField() + # ... other fields +``` + +#### API7: Server-Side Request Forgery (SSRF) + +> **Risk**: Server makes requests to attacker-controlled or internal resources + +**Real-World Impact**: +- **2019**: Capital One breach via SSRF (100M records) +- **2021**: Multiple cloud metadata service exploits + +**Attack Scenarios:** + +1. **Cloud Metadata Access** + ```http + GET /api/fetch?url=http://169.254.169.254/latest/meta-data/iam/security-credentials/ + # Retrieves AWS credentials + ``` + +2. **Internal Service Access** + ```http + GET /api/fetch?url=http://localhost:8080/admin + GET /api/fetch?url=http://internal-api.company.local/secrets + ``` + +3. **URL Bypass Techniques** + ``` + http://127.0.0.1 → localhost bypass + http://0177.0.0.1 → Octal encoding + http://2130706433 → Decimal IP + http://0x7f.0x0.0x0.0x1 → Hex encoding + http://[::ffff:127.0.0.1] → IPv6 + http://127.1 → Shortened + ``` + +4. **DNS Rebinding** + ``` + Attacker controls DNS that resolves to: + - First request: legitimate.com → 1.2.3.4 + - Second request: attacker.com → 169.254.169.254 + ``` + +**Testing Approach:** + +1. **Basic SSRF Testing**: + ```bash + # Test internal IP access + curl "https://api.example.com/fetch?url=http://169.254.169.254/" + curl "https://api.example.com/fetch?url=http://localhost:22" + curl "https://api.example.com/fetch?url=file:///etc/passwd" + ``` + +2. **Bypass Testing**: + ```bash + # Try various encodings + curl "https://api.example.com/fetch?url=http://0177.0.0.1/" + curl "https://api.example.com/fetch?url=http://2130706433/" + curl "https://api.example.com/fetch?url=http://[::ffff:127.0.0.1]/" + ``` + +3. **Port Scanning via SSRF**: + ```bash + # Test if server can reach internal ports + for port in 22 80 443 3306 5432 6379 8080; do + curl "https://api.example.com/fetch?url=http://localhost:$port" + done + ``` + +**Remediation:** +```python +import ipaddress +import re +from urllib.parse import urlparse + +def is_internal_ip(ip_str): + """Check if IP is internal/private""" + try: + ip = ipaddress.ip_address(ip_str) + return ip.is_private or ip.is_loopback or ip.is_reserved + except ValueError: + return False + +def validate_url(url): + """Validate URL for SSRF prevention""" + parsed = urlparse(url) + + # Allowlist approach (recommended) + allowed_hosts = ['api.trusted.com', 'cdn.trusted.com'] + if parsed.hostname not in allowed_hosts: + raise ValidationError("URL not in allowlist") + + # Blocklist approach (supplementary) + blocked_schemes = ['file', 'ftp', 'gopher', 'dict'] + if parsed.scheme in blocked_schemes: + raise ValidationError("Scheme not allowed") + + # Resolve and check IP + import socket + try: + ip = socket.gethostbyname(parsed.hostname) + if is_internal_ip(ip): + raise ValidationError("Internal IPs not allowed") + except socket.gaierror: + raise ValidationError("Could not resolve hostname") + + return url + +# Alternative: Use a dedicated SSRF protection library +# pip install ssrf-protect +from ssrf_protect import SSRFProtect + +@SSRFProtect() +def fetch_url(request): + url = request.GET.get('url') + # Safe to fetch + return requests.get(url) +``` + +#### API8: Security Misconfiguration + +> **Risk**: Insecure default configurations expose APIs to attacks + +**Real-World Impact**: +- **2018**: Tesla Kubernetes API exposed (cryptomining) +- **2020**: Multiple Elasticsearch instances exposed without auth + +**Attack Scenarios:** + +1. **CORS Misconfiguration** + ```http + Access-Control-Allow-Origin: * # Too permissive + Access-Control-Allow-Credentials: true # Dangerous combination + ``` + +2. **Verbose Error Messages** + ```json + { + "error": "SQL syntax error near 'user_id = 123'", + "stack_trace": "...", + "query": "SELECT * FROM users WHERE user_id = 123" + } + ``` + +3. **Missing Security Headers** + ```http + # Missing headers: + X-Content-Type-Options: nosniff + X-Frame-Options: DENY + Content-Security-Policy: ... + Strict-Transport-Security: max-age=31536000 + ``` + +4. **Debug Mode Enabled** + ``` + /api/debug/vars # Exposes Go runtime variables + /api/swagger-ui/ # API documentation with try-it feature + /api/actuator/health # Spring Boot endpoints + ``` + +**Testing Approach:** + +1. **Security Headers Check**: + ```bash + curl -I https://api.example.com/endpoint | grep -i "access-control\|x-" + ``` + +2. **Error Handling Test**: + ```bash + # Trigger errors and check responses + curl "https://api.example.com/endpoint?param=' OR 1=1--" + curl "https://api.example.com/endpoint" -X INVALID_METHOD + ``` + +3. **Debug Endpoint Discovery**: + ```bash + # Common debug paths + /debug + /actuator + /swagger-ui + /api-docs + /health + /metrics + ``` + +**Remediation:** +```python +# Django middleware for security headers +class SecurityHeadersMiddleware: + def __init__(self, get_response): + self.get_response = get_response + + def __call__(self, request): + response = self.get_response(request) + + # Security headers + response['X-Content-Type-Options'] = 'nosniff' + response['X-Frame-Options'] = 'DENY' + response['X-XSS-Protection'] = '1; mode=block' + response['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains' + response['Content-Security-Policy'] = "default-src 'self'" + response['Referrer-Policy'] = 'strict-origin-when-cross-origin' + + # CORS (restrictive) + response['Access-Control-Allow-Origin'] = 'https://trusted-domain.com' + response['Access-Control-Allow-Methods'] = 'GET, POST, PUT, DELETE' + response['Access-Control-Allow-Headers'] = 'Content-Type, Authorization' + + return response + +# Disable debug mode in production +DEBUG = False + +# Custom error handler (don't expose internals) +from django.http import JsonResponse + +def custom_error_handler(request, exception=None): + return JsonResponse( + {"error": "An error occurred"}, + status=500 + ) +``` + +#### API9: Improper Inventory Management + +> **Risk**: Shadow APIs and undocumented endpoints create attack surface + +**Real-World Impact**: +- **2021**: Facebook API exposed user data via undocumented endpoint +- **2022**: Twitter API v1.1 endpoints still accessible after v2 launch + +**Attack Scenarios:** + +1. **Shadow API Discovery** + ``` + Compare OpenAPI spec with actual code + Look for endpoints not in documentation + ``` + +2. **Deprecated API Usage** + ```http + GET /api/v1/users # Old version still active + GET /api/v2/users # New version + # v1 may have known vulnerabilities + ``` + +3. **Environment Confusion** + ``` + Production API: api.company.com + Staging API: api-staging.company.com # Exposed? + Dev API: api-dev.company.com # Exposed with debug enabled? + ``` + +**Testing Approach:** + +1. **API Inventory**: + ```bash + # Extract all routes from code + grep -r "@app.route\|@GetMapping\|path(" --include="*.py" --include="*.java" + + # Compare with OpenAPI spec + # Identify undocumented endpoints + ``` + +2. **Version Testing**: + ```bash + # Test old API versions + curl https://api.example.com/v1/users + curl https://api.example.com/v2/users + ``` + +3. **Environment Discovery**: + ```bash + # Check for exposed environments + curl https://api-staging.example.com/health + curl https://api-dev.example.com/debug + ``` + +**Remediation:** +```yaml +# API Gateway configuration (Kong example) +plugins: + - name: request-termination + config: + status_code: 410 + message: "API version deprecated" + route: api-v1-routes + +# Automated API discovery +# Use tools like: +# - OWASP ZAP API scanner +# - Postman collection generator +# - Swagger Codegen + +# Regular audits +# Monthly: Compare deployed endpoints with documentation +# Quarterly: Review and deprecate old API versions +``` + +#### API10: Unsafe Consumption of APIs + +> **Risk**: Trusting third-party API responses leads to injection attacks + +**Real-World Impact**: +- **2020**: Multiple XXE attacks via external API responses +- **2021**: Deserialization attacks from webhook payloads + +**Attack Scenarios:** + +1. **XXE via External API** + ```xml + + + + ]> + &xxe; + ``` + +2. **Deserialization Attack** + ```python + # Attacker controls serialized data + import pickle + malicious = b'...crafted pickle payload...' + data = pickle.loads(malicious) # RCE! + ``` + +3. **Webhook Replay** + ```http + # Attacker captures webhook and replays it + POST /api/webhooks/payment + X-Webhook-Signature: valid_signature + {"event": "payment.success", "amount": 1000} + + # Replay same request to double credits + ``` + +4. **JSON Injection** + ```json + // Malicious JSON from external API + { + "username": "admin", + "bio": "" + } + ``` + +**Testing Approach:** + +1. **XXE Testing**: + ```bash + # If API accepts XML from third parties + # Send malicious XML to test for XXE + ``` + +2. **Deserialization Testing**: + ```bash + # Check for unsafe deserialization + # Look for pickle, ObjectInputStream, unserialize + ``` + +3. **Webhook Security**: + ```bash + # Test webhook replay + # Check signature validation + # Verify timestamp/nonce checks + ``` + +**Remediation:** +```python +# XXE Prevention +import xml.etree.ElementTree as ET +from defusedxml import ElementTree as DefusedET + +def parse_xml_safely(xml_string): + # Use defusedxml to prevent XXE + return DefusedET.fromstring(xml_string) + +# Deserialization Safety +import json + +def safe_deserialize(data): + # Use JSON instead of pickle for untrusted data + return json.loads(data) + + # If you must use pickle, sign the data + import hmac + import hashlib + + signature = hmac.new( + SECRET_KEY, + data, + hashlib.sha256 + ).hexdigest() + + if not hmac.compare_digest(signature, expected_signature): + raise ValueError("Invalid signature") + + return pickle.loads(data) + +# Webhook Security +import hmac +import hashlib +import time + +def verify_webhook(request): + # Verify signature + signature = request.headers.get('X-Webhook-Signature') + expected = hmac.new( + WEBHOOK_SECRET, + request.body, + hashlib.sha256 + ).hexdigest() + + if not hmac.compare_digest(signature, expected): + raise ValueError("Invalid signature") + + # Check timestamp (prevent replay) + timestamp = int(request.headers.get('X-Webhook-Timestamp')) + if abs(time.time() - timestamp) > 300: # 5 minutes + raise ValueError("Request too old") + + # Check nonce (prevent replay) + nonce = request.headers.get('X-Webhook-Nonce') + if nonce in used_nonces: + raise ValueError("Nonce already used") + used_nonces.add(nonce) + + return True +``` + +### Phase 4: Automated Security Testing + +#### 4.1 API Security Scanning + +**OWASP ZAP**: +```bash +# Automated API scan +zap-api-scan.py -t https://api.example.com/openapi.json -f openapi + +# With authentication +zap-api-scan.py -t https://api.example.com/openapi.json \ + -f openapi \ + -config "replacer.full_list(0).description=auth" \ + -config "replacer.full_list(0).enabled=true" \ + -config "replacer.full_list(0).matchtype=REQ_HEADER" \ + -config "replacer.full_list(0).matchstr=Authorization" \ + -config "replacer.full_list(0).replacement=Bearer $TOKEN" +``` + +**Burp Suite**: +- Import OpenAPI spec +- Run active scan on all endpoints +- Test for BOLA, authentication bypasses + +**Postman Security Tests**: +```javascript +// Test for sensitive data in response +pm.test("Response does not contain sensitive data", function () { + pm.expect(pm.response.text()).to.not.include("password"); + pm.expect(pm.response.text()).to.not.include("secret"); +}); + +// Test for security headers +pm.test("Security headers present", function () { + pm.response.to.have.header("X-Content-Type-Options"); + pm.response.to.have.header("X-Frame-Options"); +}); +``` + +#### 4.2 Custom Security Tests + +**BOLA Testing Script**: +```python +import requests + +def test_bola(base_url, token, user_a_id, user_b_id): + """Test for Broken Object Level Authorization""" + + # Get User A's token + headers = {"Authorization": f"Bearer {token}"} + + # Try to access User B's resources + endpoints = [ + f"/api/users/{user_b_id}", + f"/api/users/{user_b_id}/orders", + f"/api/orders?user_id={user_b_id}", + ] + + for endpoint in endpoints: + response = requests.get(f"{base_url}{endpoint}", headers=headers) + if response.status_code == 200: + print(f"BOLA VULNERABILITY: {endpoint}") + print(f"User A can access User B's data!") +``` + +**Rate Limit Testing**: +```python +import requests +import time + +def test_rate_limiting(url, headers, requests_count=100): + """Test if rate limiting is enforced""" + + success_count = 0 + start_time = time.time() + + for i in range(requests_count): + response = requests.get(url, headers=headers) + if response.status_code == 200: + success_count += 1 + elif response.status_code == 429: + print(f"Rate limit hit after {i} requests") + break + + elapsed = time.time() - start_time + print(f"Made {success_count} requests in {elapsed:.2f} seconds") + + if success_count == requests_count: + print("WARNING: No rate limiting detected!") +``` + +### Phase 5: API Gateway & Infrastructure Review + +#### 5.1 Kong Gateway Configuration + +```yaml +# kong.yml +plugins: + # Rate limiting + - name: rate-limiting + config: + minute: 100 + hour: 1000 + policy: redis + redis_host: redis + + # CORS (restrictive) + - name: cors + config: + origins: + - "https://app.example.com" + methods: + - GET + - POST + - PUT + - DELETE + headers: + - Authorization + - Content-Type + credentials: true + max_age: 3600 + + # Request size limiting + - name: request-size-limiting + config: + allowed_payload_size: 10 # MB + + # Bot detection + - name: bot-detection + config: + deny: + - "Mozilla/5.0 (compatible; Googlebot/2.1)" + + # IP restriction + - name: ip-restriction + config: + allow: + - "10.0.0.0/8" + - "172.16.0.0/12" +``` + +#### 5.2 nginx Configuration + +```nginx +server { + listen 443 ssl http2; + server_name api.example.com; + + # SSL configuration + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256'; + + # Security headers + add_header X-Frame-Options "DENY" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Referrer-Policy "strict-origin-when-cross-origin" always; + + # Rate limiting + limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s; + limit_req zone=api burst=20 nodelay; + + # Request size limit + client_max_body_size 10M; + + # Timeout settings + proxy_connect_timeout 30s; + proxy_send_timeout 30s; + proxy_read_timeout 30s; + + location / { + proxy_pass http://backend; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +#### 5.3 AWS API Gateway + +```yaml +# serverless.yml or CloudFormation +Resources: + ApiGateway: + Type: AWS::ApiGateway::RestApi + Properties: + Name: SecureAPI + + # Throttling + ApiGatewayStage: + Type: AWS::ApiGateway::Stage + Properties: + RestApiId: !Ref ApiGateway + StageName: prod + MethodSettings: + - ResourcePath: /* + HttpMethod: * + ThrottlingBurstLimit: 100 + ThrottlingRateLimit: 50 + + # WAF + WebACL: + Type: AWS::WAFv2::WebACL + Properties: + Name: APIWAF + Rules: + - Name: RateLimit + Priority: 1 + Statement: + RateBasedStatement: + Limit: 2000 + AggregateKeyType: IP + Action: + Block: {} + VisibilityConfig: + SampledRequestsEnabled: true +``` + +## Output Format + +```markdown +## API Security Assessment: [API Name] + +### Executive Summary +- **API Type**: REST | GraphQL | gRPC | SOAP +- **Total Endpoints**: [count] +- **Authentication**: [JWT | OAuth 2.0 | API Keys | Session] +- **Risk Rating**: [Critical | High | Medium | Low] +- **Overall Security Posture**: [Brief assessment] + +### API Surface Inventory + +#### Authentication Mechanisms +| Mechanism | Implementation | Security Rating | +|-----------|---------------|-----------------| +| JWT | HS256, 15min expiry | ✅ Secure | +| OAuth 2.0 | PKCE enabled | ✅ Secure | + +#### Endpoint Breakdown +| Category | Count | Auth Required | +|----------|-------|---------------| +| Public | 5 | No | +| Authenticated | 45 | Yes | +| Admin | 8 | Yes + Admin role | + +### Risk Matrix + +| OWASP API Ref | Risk | Severity | Status | Evidence | +|--------------|------|----------|--------|----------| +| API1 | BOLA | HIGH | Finding | /api/orders/{id} lacks ownership check | +| API2 | Broken Auth | MEDIUM | Finding | JWT alg=none accepted | +| API3 | BOPA | HIGH | Finding | Mass assignment on /api/users | +| API4 | Resource Consumption | LOW | Finding | No rate limiting on search | +| API5 | BFLA | MEDIUM | Finding | Admin endpoints accessible to users | +| API6 | Business Flows | N/A | N/A | Not applicable | +| API7 | SSRF | CRITICAL | Finding | Cloud metadata accessible | +| API8 | Misconfiguration | MEDIUM | Finding | Debug mode enabled | +| API9 | Inventory | LOW | Finding | Undocumented /api/internal endpoints | +| API10 | Unsafe Consumption | HIGH | Finding | Webhooks lack signature validation | + +### Critical Findings + +#### [CRITICAL] API7: SSRF - Cloud Metadata Exposure +- **Location**: `/api/fetch?url=` parameter +- **Impact**: AWS credentials can be extracted, leading to full cloud compromise +- **Evidence**: + ``` + GET /api/fetch?url=http://169.254.169.254/latest/meta-data/iam/security-credentials/ + Response: 200 OK with IAM role credentials + ``` +- **Remediation**: Implement URL allowlist, block internal IPs + +### High Findings +[Additional findings...] + +### Positive Security Controls +- ✅ JWT tokens use strong signing (RS256) +- ✅ HTTPS enforced with TLS 1.2+ +- ✅ Security headers present +- ✅ Input validation on all endpoints + +### Remediation Roadmap + +#### Immediate (Critical/High - 1 week) +1. Fix SSRF vulnerability (API7) +2. Implement BOLA checks on all object endpoints (API1) +3. Disable debug mode (API8) + +#### Short-term (High/Medium - 1 month) +4. Implement comprehensive rate limiting (API4) +5. Add field-level authorization (API3) +6. Secure admin endpoints (API5) + +#### Long-term (Medium/Low - 3 months) +7. Implement API inventory management (API9) +8. Add webhook signature validation (API10) +9. Conduct regular security testing + +### Testing Artifacts +- [ ] OWASP ZAP scan results +- [ ] Burp Suite scan results +- [ ] Custom test scripts output +- [ ] API gateway configuration review + +### References +- OWASP API Security Top 10 (2023) +- OWASP ASVS v5.0 - V13: API and Web Service +- OWASP Testing Guide: WSTG-APIT +``` + +## OWASP References + +- **OWASP API Security Top 10 (2023)** — [owasp.org/API-Security](https://owasp.org/API-Security/) +- **OWASP ASVS v5.0** — V13: API and Web Service Verification +- **OWASP Testing Guide** — WSTG-APIT: API Testing +- **OWASP Cheat Sheet Series**: + - REST Security + - GraphQL Security + - JWT Security + - OAuth 2.0 + - SAML Security +- **OWASP ZAP** — API scanning capabilities diff --git a/skills/code-review-security/plays/code-review-security.md b/skills/code-review-security/plays/code-review-security.md new file mode 100644 index 0000000..0b4038a --- /dev/null +++ b/skills/code-review-security/plays/code-review-security.md @@ -0,0 +1,204 @@ +# Play: Security Code Review + +A security code review identifies vulnerabilities in application logic, authentication, authorization, cryptography, and data handling. This play structures the review around OWASP weakness classes (injection, auth, crypto, etc.) and is applicable to any language or framework. Reviews can target full codebases, pull request diffs, or specific modules, and findings are mapped to OWASP standards and OpenCRE for multi-framework traceability. + +Review code changes or codebases for security vulnerabilities, mapping findings to OWASP standards and OpenCRE cross-references for multi-framework traceability. + +## Trigger Conditions + +Use this skill when: +- Reviewing a pull request or diff for security issues +- A user asks for a security review of their code +- Auditing a specific file, module, or feature for vulnerabilities +- Performing a pre-merge security gate check + +## Inputs + +- Code diff (PR), specific files, or entire codebase to review +- (Optional) Language and framework context +- (Optional) ASVS level to verify against (L1, L2, or L3) +- (Optional) Specific concern areas to focus on + +## Procedure + +### 1. Scope & Context + +Before diving in, establish: +- **Language/Framework**: Determines which vulnerability classes are relevant +- **Trust boundary**: Is this server-side, client-side, library, CLI, infrastructure code? +- **Data sensitivity**: Does this code handle PII, credentials, financial data, health data? +- **Exposure**: Is this internet-facing, internal, or local-only? + +### 2. Systematic Review by Vulnerability Class + +Review in priority order — highest-impact classes first: + +#### A. Injection (CWE-74, OWASP A03, [OpenCRE 161-451](https://www.opencre.org/cre/161-451)) + +> ASVS refs: `data/asvs/V12.1.md` (Input Validation), `data/asvs/V13.1.md` (Output Encoding), `data/asvs/V5.3.md` (File Storage) + +| Subtype | What to Look For | +|---------|-----------------| +| SQL Injection | String concatenation in queries, missing parameterization, ORM raw queries | +| Command Injection | User input in exec/spawn/system calls, unsanitized shell arguments | +| XSS | User input rendered without output encoding, unsafe DOM manipulation, unescaped template output | +| SSTI | User input in template strings that get evaluated server-side | +| LDAP Injection | User input in LDAP filters without escaping | +| Path Traversal | User input in file paths without canonicalization, `../` not blocked | +| Header Injection | User input in HTTP headers (CRLF injection) | +| Log Injection | User input written to logs without sanitization | + +#### B. Authentication & Session (CWE-287, OWASP A07, [OpenCRE 633-428](https://www.opencre.org/cre/633-428)) + +> ASVS refs: `data/asvs/V2.1.md`–`V2.4.md` (Authentication), `data/asvs/V3.1.md`–`V3.7.md` (Session Management) + +- Hardcoded credentials or API keys +- Missing authentication on endpoints +- Weak password requirements +- Session tokens in URLs or logs +- Missing session invalidation on logout/password change +- JWT issues: none algorithm, missing expiry, weak signing key, secrets in payload +- Missing MFA enforcement for sensitive operations + +#### C. Authorization (CWE-862, OWASP A01, [OpenCRE 724-770](https://www.opencre.org/cre/724-770)) + +> ASVS refs: `data/asvs/V4.1.md`–`V4.4.md` (Access Control) + +- Missing authorization checks on endpoints or functions +- IDOR: object references without ownership validation +- Horizontal privilege escalation (accessing other users' data) +- Vertical privilege escalation (accessing admin functions) +- Missing RBAC/ABAC enforcement +- Direct database queries that don't filter by user/tenant + +#### D. Cryptography (CWE-327, OWASP A02, [OpenCRE 278-646](https://www.opencre.org/cre/278-646)) + +> ASVS refs: `data/asvs/V6.1.md`–`V6.8.md` (Cryptography) + +- Weak algorithms: MD5, SHA1 for passwords, DES, RC4 +- ECB mode usage +- Hardcoded encryption keys or IVs +- Missing encryption at rest for sensitive data +- Missing TLS enforcement +- Custom crypto implementations (don't roll your own) +- Insufficient key lengths (RSA < 2048, AES < 128) + +#### E. Data Exposure (CWE-200, OWASP A01, [OpenCRE 126-668](https://www.opencre.org/cre/126-668)) + +> ASVS refs: `data/asvs/V8.1.md`–`V8.4.md` (Data Protection), `data/asvs/V7.1.md`–`V7.6.md` (Error Handling & Logging) + +- Sensitive data in error messages or stack traces +- Verbose logging of requests/responses containing PII +- Credentials or tokens in source code, configs, or URLs +- Missing response headers (X-Content-Type-Options, etc.) +- API responses including more fields than necessary +- Debug mode enabled in production configs + +#### F. Security Misconfiguration (OWASP A05, [OpenCRE 233-748](https://www.opencre.org/cre/233-748)) + +> ASVS refs: `data/asvs/V10.1.md`–`V10.7.md` (Configuration) + +- Default credentials or configurations +- Unnecessary features enabled (debug endpoints, admin panels) +- Missing security headers +- Overly permissive CORS +- Directory listing enabled +- Missing rate limiting on sensitive endpoints + +#### G. Deserialization & Data Integrity (CWE-502, OWASP A08, [OpenCRE 854-643](https://www.opencre.org/cre/854-643)) + +> ASVS refs: `data/asvs/V11.1.md`–`V11.7.md` (Business Logic) + +- Deserializing untrusted data (unsafe deserialization in any language — Python, Java, PHP, Ruby, .NET) +- Missing integrity checks on data from untrusted sources +- Unsigned cookies or tokens +- Missing CSRF protection on state-changing operations + +### 3. Framework-Specific Checks + +Apply checks specific to the detected framework: + +| Framework | Key Checks | +|-----------|-----------| +| React/Next.js | XSS via unsafe HTML rendering, SSRF in server-side data fetching, exposed API routes | +| Express/Node | Missing helmet, no rate limiting, prototype pollution, regex DoS | +| Django | Raw SQL, CSRF exemptions, DEBUG=True, SECRET_KEY exposure | +| Flask | Jinja2 autoescape disabled, unsafe session serialization, debug mode | +| Spring | SpEL injection, actuator exposure, mass assignment | +| Rails | Mass assignment, render user input, SQL fragments | +| Go net/http | Missing timeouts, TOCTOU in file operations, integer overflow | + +### 4. Diff-Specific Analysis (for PR reviews) + +When reviewing a diff rather than a full codebase: +- Focus on changed lines and their immediate context +- Check if security controls in surrounding (unchanged) code are preserved +- Verify that new endpoints have auth/authz matching existing patterns +- Check if new dependencies introduce vulnerabilities (cross-reference with sca-audit) +- Look for removed security controls (deleted validation, removed auth checks) + +### 5. Produce Findings + +For each issue: +- Cite the specific code location (file:line) +- Show the vulnerable code snippet +- Explain the attack scenario concretely +- Provide a fixed code snippet +- Rate confidence (HIGH if confirmed path, MEDIUM if contextual, LOW if heuristic) + +## Output Format + +```markdown +## Security Code Review: [Target] + +### Scope +- **Files reviewed**: [count or list] +- **Language/Framework**: [detected] +- **Review type**: Full | PR diff | Targeted + +### Findings +[Standard finding template for each issue, sorted by severity] + +### Positive Observations +[Security controls that ARE in place — acknowledge good practices] + +### Summary +| Severity | Count | +|----------|-------| +| CRITICAL | N | +| HIGH | N | +| MEDIUM | N | +| LOW | N | +| INFO | N | +``` + +## Tools & Resources + +### Static Analysis Tools +- **Semgrep** — Multi-language pattern-based SAST; highly customizable rules +- **CodeQL (GitHub)** — Query-based code analysis for Java, C++, C#, Go, Python, TypeScript, JavaScript, Ruby +- **SonarQube** — Code quality and security scanning with OWASP Top 10 mappings +- **Checkmarx/CxSAST** — Enterprise SAST with custom rule authoring +- **Snyk Code** — Developer-first SAST integrated into IDEs and CI/CD + +### Language-Specific +- **Bandit** (Python) — Finds common security issues in Python code +- **Brakeman** (Ruby) — Scans Rails apps for OWASP risks +- **go-vuln-check** (Go) — Detects known vulnerabilities in Go code +- **ShiftLeft/Taint** (Java, Python, Go) — Data flow analysis for injection detection + +### Code Review Checkers +- **OWASP Cheat Sheet Series** — Per-vulnerability quick guides and remediation +- **CWE Top 25** — Prioritized list of most dangerous weakness patterns +- **ASVS Interactive** — Maps review items to ASVS verification levels (L1/L2/L3) + +## References + +- OWASP Top 10 (2021): A01-A10 +- OWASP ASVS v5.0 (for verification-level mapping) +- OWASP Code Review Guide +- OWASP Cheat Sheet Series (per-topic) +- OWASP Proactive Controls +- [OpenCRE](https://www.opencre.org) — Cross-standard requirement mappings (CWE, ASVS, WSTG, NIST 800-53, ISO 27001) +- [CWE](https://cwe.mitre.org) v4.19 — Common Weakness Enumeration +- ASVS 5.0 reference data in `data/asvs/` — sourced from [OWASP Agent Skills Project](https://github.com/eoftedal/owasp-agent-skills-project) diff --git a/skills/code-review-security/templates/finding.md b/skills/code-review-security/templates/finding.md new file mode 100644 index 0000000..65ea1a3 --- /dev/null +++ b/skills/code-review-security/templates/finding.md @@ -0,0 +1,48 @@ +# Finding Template + +Use this structure for all security findings produced by skills. + +```markdown +### [SEVERITY] Title + +- **ID**: NDC-YYYY-NNN (auto-incrementing) +- **CWE**: CWE-XXX (if applicable) +- **CVE**: CVE-YYYY-NNNNN (if applicable) +- **OpenCRE**: [CRE-ID](https://www.opencre.org/cre/CRE-ID) — requirement name (see data/opencre/) +- **OWASP Ref**: Top 10 A01, ASVS V4.1.1, MASVS-STORAGE-1, MASWE-0001, MASTG-TEST-0200, LLM01, etc. +- **Location**: file_path:line_number or component name +- **Impact**: What an attacker can achieve (1-2 sentences) +- **Evidence**: Code snippet, command output, or proof-of-concept +- **Remediation**: Specific fix with code example +- **Confidence**: HIGH | MEDIUM | LOW (how certain is this finding) +``` + +### Resolving OpenCRE Links + +When you have a CWE, look up its OpenCRE mapping via the API: + +``` +GET https://www.opencre.org/rest/v1/standard/CWE/sectionid/{cwe-number} +``` + +This returns the CRE ID and linked standards (ASVS, WSTG, NIST 800-53, cheat sheets). Include the CRE link in findings to give readers one-click access to all related standards and remediation guidance. + +Common mappings are pre-populated in `data/opencre/README.md`. + +## Severity Definitions + +| Severity | CVSS Range | Criteria | +|----------|-----------|----------| +| CRITICAL | 9.0-10.0 | Remote code execution, full system compromise, mass data breach | +| HIGH | 7.0-8.9 | Privilege escalation, significant data exposure, auth bypass | +| MEDIUM | 4.0-6.9 | Limited data exposure, requires user interaction or specific conditions | +| LOW | 0.1-3.9 | Information disclosure, minor misconfigurations | +| INFORMATIONAL | N/A | Best practice recommendations, defense-in-depth suggestions | + +## Confidence Levels + +| Level | Meaning | +|-------|---------| +| HIGH | Confirmed via code path analysis, PoC, or tool output | +| MEDIUM | Strong indicators but not fully confirmed — needs manual verification | +| LOW | Heuristic match or pattern-based — may be false positive | diff --git a/skills/cve-triage/SKILL.md b/skills/cve-triage/SKILL.md index 9439de7..0754c1e 100644 --- a/skills/cve-triage/SKILL.md +++ b/skills/cve-triage/SKILL.md @@ -415,7 +415,7 @@ When triaging multiple CVEs (e.g., from a scan report), produce a summary table - **Blind spots:** This skill depends on available code, configuration, logs, documentation, and user-provided context; it cannot prove controls exist or threats are absent when evidence is missing, runtime-only, or outside the review scope. - **False-positive risks:** Treat findings as hypotheses until validated against asset criticality, compensating controls, environment intent, and recent authorized changes. - **Required evidence:** Support each finding with concrete artifacts such as file paths and line numbers, policy snippets, scanner output, logs, screenshots, control records, or reproducible steps. -- **Normalized JSON:** When machine-readable output is requested, findings MUST be available as JSON that validates against [`schemas/finding.schema.json`](../../../schemas/finding.schema.json). +- **Normalized JSON:** When machine-readable output is requested, findings MUST be available as JSON that validates against [`schemas/finding.schema.json`](schemas/finding.schema.json). - **Escalation rules:** Escalate immediately for suspected active compromise, exposed secrets, regulated-data exposure, critical exploitable vulnerabilities, privileged-access abuse, or when evidence is insufficient to safely disposition a high-impact risk. --- diff --git a/skills/cve-triage/schemas/finding.schema.json b/skills/cve-triage/schemas/finding.schema.json new file mode 100644 index 0000000..535a496 --- /dev/null +++ b/skills/cve-triage/schemas/finding.schema.json @@ -0,0 +1,345 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/UnitOneAI/SecuritySkills/schemas/finding.schema.json", + "title": "SecuritySkills Normalized Finding Output", + "description": "Machine-readable envelope for normalized security findings and remediation recommendations emitted by SecuritySkills workflows. This contract is independent of SARIF and may be mapped to downstream enterprise formats later.", + "type": "object", + "additionalProperties": false, + "required": ["schema_version", "run", "skill", "findings"], + "properties": { + "schema_version": { + "const": "1.0.0", + "description": "Version of this normalized SecuritySkills finding envelope." + }, + "run": { + "$ref": "#/$defs/run", + "description": "Metadata for the analysis run that produced this output." + }, + "skill": { + "$ref": "#/$defs/skill", + "description": "Metadata for the SecuritySkills entrypoint that produced this output." + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/$defs/finding" + }, + "description": "Normalized findings produced by a skill run." + } + }, + "$defs": { + "riskLevel": { + "type": "string", + "enum": ["low", "medium", "high"] + }, + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "uriString": { + "type": "string", + "format": "uri" + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": ["id", "timestamp"], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable run identifier supplied by the agent, CI job, or enterprise orchestrator." + }, + "timestamp": { + "$ref": "#/$defs/nonEmptyString", + "description": "ISO 8601 timestamp for when the run output was produced." + }, + "tool": { + "$ref": "#/$defs/nonEmptyString", + "description": "Agent, CLI, scanner, or workflow that executed the skill." + }, + "target": { + "$ref": "#/$defs/nonEmptyString", + "description": "Repository, project, service, artifact, environment, or other target reviewed." + }, + "source_ref": { + "$ref": "#/$defs/nonEmptyString", + "description": "Optional commit SHA, branch, image digest, build ID, ticket ID, or evidence package reference." + } + } + }, + "skill": { + "type": "object", + "additionalProperties": false, + "required": ["name", "version"], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString", + "description": "SecuritySkills skill name from SKILL.md frontmatter." + }, + "version": { + "$ref": "#/$defs/nonEmptyString", + "description": "SecuritySkills skill version from SKILL.md frontmatter." + }, + "path": { + "$ref": "#/$defs/nonEmptyString", + "description": "Path to the SKILL.md entrypoint used for the run." + }, + "frameworks": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": "Framework identifiers declared by the skill frontmatter." + } + } + }, + "finding": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "severity", "status", "evidence", "remediations"], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable finding identifier within the output." + }, + "fingerprint": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable deduplication key based on finding type, affected asset, and evidence location." + }, + "title": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "$ref": "#/$defs/nonEmptyString", + "description": "What the issue is and why it matters." + }, + "severity": { + "type": "string", + "enum": ["info", "low", "medium", "high", "critical"] + }, + "status": { + "type": "string", + "enum": ["open", "mitigated", "accepted_risk", "false_positive"] + }, + "cwe": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "pattern": "^CWE-[0-9]+$" + }, + "description": "Optional CWE mappings, when applicable." + }, + "framework_refs": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/frameworkRef" + }, + "description": "Framework/control references from the skill frontmatter frameworks." + }, + "references": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/reference" + }, + "description": "Optional advisory, standard, vendor, or knowledge-base references." + }, + "evidence": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["location", "summary"], + "properties": { + "location": { + "$ref": "#/$defs/nonEmptyString", + "description": "File path, line range, asset ID, log source, policy path, or other concrete evidence location." + }, + "summary": { + "$ref": "#/$defs/nonEmptyString" + }, + "artifact_type": { + "type": "string", + "enum": ["source", "config", "policy", "log", "scan_result", "cloud_resource", "identity", "network", "document", "other"] + }, + "snippet": { + "$ref": "#/$defs/nonEmptyString", + "description": "Minimal redacted snippet or observation needed to support the finding." + }, + "redacted": { + "type": "boolean", + "description": "True when sensitive values were intentionally removed from this evidence." + } + } + } + }, + "remediations": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/remediation" + }, + "description": "Every fix recommendation for this finding. Each item must include remediation guidance, confidence, blast radius, behavior-change risk, and test strategy." + } + }, + "anyOf": [ + { + "required": ["cwe"] + }, + { + "required": ["framework_refs"] + } + ] + }, + "frameworkRef": { + "type": "object", + "additionalProperties": false, + "required": ["framework", "control"], + "properties": { + "framework": { + "$ref": "#/$defs/nonEmptyString" + }, + "control": { + "$ref": "#/$defs/nonEmptyString" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "reference": { + "type": "object", + "additionalProperties": false, + "required": ["type", "id"], + "properties": { + "type": { + "type": "string", + "enum": ["cve", "cwe", "framework", "advisory", "vendor", "documentation", "other"] + }, + "id": { + "$ref": "#/$defs/nonEmptyString" + }, + "url": { + "$ref": "#/$defs/uriString" + } + } + }, + "remediation": { + "type": "object", + "additionalProperties": false, + "required": ["guidance", "confidence", "blast_radius", "behavior_change_risk", "test_strategy"], + "properties": { + "guidance": { + "$ref": "#/$defs/nonEmptyString", + "description": "Concrete remediation steps or patch guidance for the finding." + }, + "confidence": { + "$ref": "#/$defs/riskLevel", + "description": "How confident the skill is that this recommendation is correct for the observed evidence." + }, + "blast_radius": { + "$ref": "#/$defs/nonEmptyString", + "description": "Expected scope of systems, files, users, integrations, data, or workflows affected by the change." + }, + "behavior_change_risk": { + "$ref": "#/$defs/riskLevel", + "description": "Risk that the remediation changes intended application or operational behavior." + }, + "test_strategy": { + "$ref": "#/$defs/testStrategy", + "description": "Required validation strategy proving the remediation fixes the finding. Include recommended tests, generated tests, or both." + } + } + }, + "testStrategy": { + "type": "object", + "additionalProperties": false, + "required": ["summary"], + "properties": { + "summary": { + "$ref": "#/$defs/nonEmptyString", + "description": "Concise explanation of what proves the remediation fixed the issue." + }, + "recommended_tests": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/recommendedTest" + }, + "description": "Tests the user or agent should run when tests are not generated directly." + }, + "generated_tests": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/generatedTest" + }, + "description": "Test files or cases produced as part of the remediation." + } + }, + "anyOf": [ + { + "required": ["recommended_tests"] + }, + { + "required": ["generated_tests"] + } + ] + }, + "recommendedTest": { + "type": "object", + "additionalProperties": false, + "required": ["name", "type", "purpose", "command", "expected_result"], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "type": { + "type": "string", + "enum": ["static", "unit", "integration", "e2e", "regression", "manual"] + }, + "purpose": { + "$ref": "#/$defs/nonEmptyString", + "description": "Behavior, vulnerability condition, or regression this test proves." + }, + "command": { + "$ref": "#/$defs/nonEmptyString", + "description": "Command or manual check to execute for this test." + }, + "expected_result": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "generatedTest": { + "type": "object", + "additionalProperties": false, + "required": ["path", "type", "purpose", "command", "expected_result"], + "properties": { + "path": { + "$ref": "#/$defs/nonEmptyString", + "description": "Path to the generated or modified test file." + }, + "type": { + "type": "string", + "enum": ["static", "unit", "integration", "e2e", "regression"] + }, + "purpose": { + "$ref": "#/$defs/nonEmptyString", + "description": "Behavior, vulnerability condition, or regression this generated test proves." + }, + "command": { + "$ref": "#/$defs/nonEmptyString", + "description": "Command that runs the generated test." + }, + "expected_result": { + "$ref": "#/$defs/nonEmptyString" + } + } + } + } +} diff --git a/skills/dependency-scanning/SKILL.md b/skills/dependency-scanning/SKILL.md index 07a4ad3..993c4e4 100644 --- a/skills/dependency-scanning/SKILL.md +++ b/skills/dependency-scanning/SKILL.md @@ -183,7 +183,7 @@ Typosquatting (also called dependency confusion or combosquatting) is a supply c ## Assessment Output Template -Before applying or proposing dependency changes, classify each remediation path using [Security Fixer Policy](../../../docs/fixer-policy.md). Include the policy review gate, reviewer evidence, and rollback guidance in the remediation plan. +Before applying or proposing dependency changes, classify each remediation path using [Security Fixer Policy](docs/fixer-policy.md). Include the policy review gate, reviewer evidence, and rollback guidance in the remediation plan. When performing a dependency scan, produce findings in the following structure: @@ -236,8 +236,8 @@ When performing a dependency scan, produce findings in the following structure: - **Blind spots:** This skill depends on available code, configuration, logs, documentation, and user-provided context; it cannot prove controls exist or threats are absent when evidence is missing, runtime-only, or outside the review scope. - **False-positive risks:** Treat findings as hypotheses until validated against asset criticality, compensating controls, environment intent, and recent authorized changes. - **Required evidence:** Support each finding with concrete artifacts such as file paths and line numbers, policy snippets, scanner output, logs, screenshots, control records, or reproducible steps. -- **Normalized JSON:** When machine-readable output is requested, findings MUST be available as JSON that validates against [`schemas/finding.schema.json`](../../../schemas/finding.schema.json). -- **SARIF JSON:** When SARIF output is requested, map normalized findings to SARIF 2.1.0-compatible JSON using [`docs/sarif-output.md`](../../../docs/sarif-output.md). +- **Normalized JSON:** When machine-readable output is requested, findings MUST be available as JSON that validates against [`schemas/finding.schema.json`](schemas/finding.schema.json). +- **SARIF JSON:** When SARIF output is requested, map normalized findings to SARIF 2.1.0-compatible JSON using [`docs/sarif-output.md`](docs/sarif-output.md). - **Escalation rules:** Escalate immediately for suspected active compromise, exposed secrets, regulated-data exposure, critical exploitable vulnerabilities, privileged-access abuse, or when evidence is insufficient to safely disposition a high-impact risk. --- diff --git a/skills/dependency-scanning/docs/fixer-policy.md b/skills/dependency-scanning/docs/fixer-policy.md new file mode 100644 index 0000000..58367f3 --- /dev/null +++ b/skills/dependency-scanning/docs/fixer-policy.md @@ -0,0 +1,111 @@ +# Security Fixer Policy + +This policy classifies security findings by how an agent may remediate them. Fixer-capable skills must use this policy before changing files, generating patches, or recommending an automated remediation path. + +## Categories + +### Auto-fix + +The agent may apply the fix directly when the finding is high-confidence, the change is narrow, and the expected behavior is mechanically verifiable. + +Criteria: +- The vulnerable pattern and target file are unambiguous. +- The fix is deterministic and follows an existing project convention or a well-known safe default. +- The change has low blast radius and does not alter public APIs, authorization semantics, data models, deployment topology, or runtime trust boundaries. +- The agent can run or define a concrete verification step. + +Examples: +- Add missing security headers in a local framework configuration using the project's existing middleware pattern. +- Replace string-built SQL with parameter binding when the query shape and parameters are clear. +- Pin a container image tag or GitHub Action version when the intended version is known from lock files, release metadata, or existing repository conventions. +- Add a `.dockerignore` or `.gitignore` entry for `.env` files without removing or exposing secret values. + +### Assisted-fix + +The agent may prepare a patch or exact commands, but the user or repository owner must confirm context, run environment-specific checks, or choose among valid alternatives before merge. + +Criteria: +- The finding is valid, but the best remediation depends on application behavior, deployment constraints, ownership boundaries, or compatibility requirements. +- Multiple safe remediation options exist. +- The change is moderate in scope or requires coordinated validation outside the local workspace. +- The agent can reduce the work to a reviewable patch, migration plan, configuration diff, or decision list. + +Examples: +- Add authorization middleware to an endpoint when the correct role or ownership predicate needs product confirmation. +- Upgrade a vulnerable dependency across a major version boundary. +- Tighten CI permissions where release, package, or deployment jobs may need specific write scopes. +- Add Kubernetes `NetworkPolicy` rules where service communication requirements must be confirmed. + +### Guidance-only + +The agent must not modify files. It should explain the finding, risk, and recommended remediation path. + +Criteria: +- The remediation requires organizational policy, architecture changes, vendor configuration, legal review, procurement, or manual operational work. +- The agent lacks access to the system that must be changed. +- The change cannot be represented safely as a local patch. + +Examples: +- Adopt a centralized secrets manager across teams. +- Establish a vulnerability management SLA. +- Change cloud account guardrails, identity provider policy, or production firewall rules outside the repository. +- Resolve license obligations for GPL, AGPL, commercial, unknown, or no-license dependencies. + +### Human-review-required + +The agent must stop short of applying a fix and explicitly request human review before remediation proceeds. + +Criteria: +- A hard gate below applies. +- The finding involves sensitive credentials, production access, destructive operations, legal/compliance interpretation, or security-critical logic. +- The agent cannot confidently preserve intended behavior. +- The evidence is incomplete or the finding may be a false positive with material operational impact. + +Examples: +- Rotate leaked credentials or revoke certificates. +- Change authentication, authorization, cryptography, payment, medical, safety, or tenant-isolation logic. +- Modify production deployment, incident response, or containment procedures. +- Apply a remediation that deletes data, removes audit evidence, weakens controls, or accepts risk. + +## Decision Criteria + +Classify each finding using the most restrictive category that applies. + +1. Confirm the finding is in scope for the skill and supported by concrete evidence. +2. Determine whether any hard gate forces human review. +3. Estimate blast radius: local config or code path, cross-cutting application behavior, infrastructure, production operations, or organizational policy. +4. Check remediation confidence: deterministic patch, multiple valid options, missing context, or uncertain behavior. +5. Check verification: automated test or scan, manual validation, external approval, or no reliable verification available. +6. Choose the category: + - Use auto-fix only when evidence, scope, remediation, and verification are all strong. + - Use assisted-fix when a patch is useful but context or approval is required. + - Use guidance-only when local code changes are not the right remediation vehicle. + - Use human-review-required whenever a hard gate applies or safe behavior preservation is uncertain. + +## Hard Gates for Human Review + +Any of these conditions forces `human-review-required`: + +- Secret exposure requiring credential rotation, revocation, certificate replacement, or git history rewriting. +- Authentication, authorization, session management, cryptographic, payment, tenant isolation, or safety-critical logic changes. +- Production infrastructure, network, identity, IAM, deployment, incident response, or data retention changes. +- Destructive or irreversible actions, including deleting data, rewriting history, disabling audit logs, removing evidence, or changing backups. +- Legal, compliance, privacy, or license-risk decisions. +- Changes requiring owner-specific business rules, threat model assumptions, regulatory interpretation, or risk acceptance. +- Unclear ownership, missing tests for a high-impact path, conflicting framework guidance, or evidence that the finding may be a false positive. +- Any remediation that would weaken an existing security control to make a tool pass. + +## Fixer Workflow Review Gates + +Fixer-capable workflows must pass these gates before any applied patch is considered ready for handoff: + +1. **Scope gate:** State the files, settings, and behaviors that are in scope; avoid unrelated refactors, formatting churn, dependency updates, or opportunistic cleanup. +2. **Approval gate:** Request explicit approval before assisted-fix or human-review-required work proceeds, and before any change that affects hard-gated areas even when a patch can be drafted. +3. **Review gate:** Provide reviewer evidence that includes the finding, policy category, changed files, behavior-change risk, verification performed or still required, and any assumptions the reviewer must confirm. +4. **Rollback gate:** Provide rollback guidance for every proposed or applied change, including the exact revert path when local patches are used or the operational rollback owner when the change cannot be reverted locally. + +Applied fixes must be isolated to the smallest viable patch. If the agent discovers unrelated defects while fixing, it should report them separately instead of expanding the patch. If rollback is unclear, expensive, or depends on production state, classify the remediation as `human-review-required`. + +## Skill Usage + +Fixer-capable skills must reference this policy when producing remediation guidance or patches. Their workflows must include the review gates above and must not apply changes until the selected category allows it. The policy classifies the remediation path only; it does not change finding schemas or require new output fields. diff --git a/skills/dependency-scanning/docs/normalized-json-output.md b/skills/dependency-scanning/docs/normalized-json-output.md new file mode 100644 index 0000000..70503c1 --- /dev/null +++ b/skills/dependency-scanning/docs/normalized-json-output.md @@ -0,0 +1,158 @@ +# Normalized JSON Output Contract + +SecuritySkills can emit machine-readable findings as a normalized JSON envelope +that validates against [`schemas/finding.schema.json`](../schemas/finding.schema.json). +This contract is independent of SARIF. Downstream systems may map it to SARIF, +ticketing systems, GRC platforms, dashboards, or vulnerability stores without +changing individual skill output rules. +See [`docs/sarif-output.md`](sarif-output.md) for the repo-level SARIF 2.1.0 +export mapping. + +## Envelope + +Every JSON response uses this top-level shape: + +```json +{ + "schema_version": "1.0.0", + "run": { + "id": "run-2026-06-16T12:00:00Z", + "timestamp": "2026-06-16T12:00:00Z", + "tool": "codex", + "target": "github.com/example/service", + "source_ref": "commit-or-build-id" + }, + "skill": { + "name": "secure-code-review", + "version": "1.0.0", + "path": "skills/appsec/secure-code-review/SKILL.md", + "frameworks": ["OWASP-ASVS-4.0.3", "CWE"] + }, + "findings": [] +} +``` + +- `schema_version` is fixed at `1.0.0` until a breaking contract change is + required. +- `run.id` is the deduplication boundary for one execution. Use an orchestrator + ID, CI job ID, or generated run ID. +- `run.timestamp` should be an ISO 8601 timestamp. +- `run.target` identifies the reviewed repository, project, service, artifact, + environment, or evidence package. +- `skill.name`, `skill.version`, and `skill.frameworks` come from the skill's + `SKILL.md` frontmatter. + +## Findings + +Each finding must include: + +- `id`: stable finding ID within the run. +- `title`: concise finding title. +- `severity`: one of `info`, `low`, `medium`, `high`, or `critical`. +- `status`: one of `open`, `mitigated`, `accepted_risk`, or `false_positive`. +- `evidence`: one or more concrete evidence entries. +- `remediations`: one or more remediation recommendations, each with a test + strategy. + +Each finding must include at least one framework/CWE mapping: + +- `cwe`: array of CWE IDs such as `CWE-89`, when applicable. +- `framework_refs`: array of framework/control references from the skill's + declared frameworks. + +Optional fields such as `fingerprint`, `description`, and `references` support +enterprise deduplication, analyst context, and external advisory linking. + +## Evidence + +Evidence entries must identify where the issue was observed and summarize the +observation. Locations may be source paths, line ranges, cloud resource IDs, log +sources, policy paths, scanner result identifiers, or evidence package records. + +Use `snippet` only for the minimal redacted text needed to prove the finding. +Set `redacted: true` when secrets, tokens, personal data, internal hostnames, or +other sensitive values were removed. + +## Remediation And Tests + +Each remediation item must include: + +- `guidance`: concrete remediation steps or patch guidance. +- `confidence`: `low`, `medium`, or `high`. +- `blast_radius`: expected affected files, systems, users, integrations, data, + or workflows. +- `behavior_change_risk`: `low`, `medium`, or `high`. +- `test_strategy`: validation that proves the issue is fixed. + +`test_strategy` must include a `summary` and at least one of +`recommended_tests` or `generated_tests`. See +[`docs/remediation-output.md`](remediation-output.md) for remediation-specific +field guidance. + +## Minimal Example + +```json +{ + "schema_version": "1.0.0", + "run": { + "id": "run-001", + "timestamp": "2026-06-16T12:00:00Z", + "tool": "codex", + "target": "payments-api", + "source_ref": "abc1234" + }, + "skill": { + "name": "api-security", + "version": "1.0.0", + "path": "skills/appsec/api-security/SKILL.md", + "frameworks": ["OWASP-API-Top-10-2023", "CWE"] + }, + "findings": [ + { + "id": "API-SEC-001", + "fingerprint": "api-security:users-delete:missing-admin-auth", + "title": "Administrative endpoint lacks authorization check", + "description": "The delete-user route accepts authenticated requests without verifying administrative privileges.", + "severity": "high", + "status": "open", + "cwe": ["CWE-862"], + "framework_refs": [ + { + "framework": "OWASP-API-Top-10-2023", + "control": "API5:2023", + "name": "Broken Function Level Authorization" + } + ], + "evidence": [ + { + "location": "routes/users.js:42", + "artifact_type": "source", + "summary": "DELETE /users/:id checks authentication but not administrator role.", + "snippet": "router.delete('/users/:id', requireAuth, deleteUser)", + "redacted": false + } + ], + "remediations": [ + { + "guidance": "Require an administrator role check before invoking deleteUser.", + "confidence": "high", + "blast_radius": "User administration routes only.", + "behavior_change_risk": "medium", + "test_strategy": { + "summary": "Proves non-admin users cannot delete accounts while admins still can.", + "recommended_tests": [ + { + "name": "Reject non-admin delete", + "type": "integration", + "purpose": "Confirms the vulnerable authorization bypass no longer succeeds.", + "command": "npm test -- users-authz.test.js", + "expected_result": "Non-admin DELETE /users/:id returns 403 and admin DELETE succeeds." + } + ] + } + } + ] + } + ] +} +``` diff --git a/skills/dependency-scanning/docs/sarif-output.md b/skills/dependency-scanning/docs/sarif-output.md new file mode 100644 index 0000000..d268c49 --- /dev/null +++ b/skills/dependency-scanning/docs/sarif-output.md @@ -0,0 +1,229 @@ +# SARIF Output Mapping + +SecuritySkills may emit SARIF-compatible JSON for tools that ingest Static +Analysis Results Interchange Format (SARIF) 2.1.0. SARIF output is an export +view of the normalized finding envelope documented in +[`docs/normalized-json-output.md`](normalized-json-output.md); it does not +replace the normalized JSON contract or change the required finding fields. + +## Top-Level Shape + +Use SARIF version `2.1.0` with the standard schema URI: + +```json +{ + "$schema": "https://json.schemastore.org/sarif-2.1.0.json", + "version": "2.1.0", + "runs": [ + { + "tool": { + "driver": { + "name": "SecuritySkills", + "semanticVersion": "1.0.0", + "rules": [] + } + }, + "results": [] + } + ] +} +``` + +Use one `run` per normalized envelope. `run.tool.driver.name` should identify +SecuritySkills or the executing agent. `run.tool.driver.semanticVersion` should +use the skill version when a single skill produced the run. + +## Mapping + +Map normalized fields to SARIF as follows: + +| Normalized field | SARIF field | +|---|---| +| `run.id`, `run.timestamp`, `run.target`, `run.source_ref` | `runs[].properties.securityskills.run` | +| `skill.name`, `skill.version`, `skill.path`, `skill.frameworks` | `runs[].tool.driver.name`, `runs[].tool.driver.semanticVersion`, `runs[].properties.securityskills.skill` | +| `finding.id` | `results[].ruleId` and `results[].properties.securityskills.finding_id` | +| `finding.fingerprint` | `results[].partialFingerprints.securityskillsFingerprint` | +| `finding.title` | `tool.driver.rules[].shortDescription.text` | +| `finding.description` | `tool.driver.rules[].fullDescription.text` and `results[].message.text` | +| `finding.severity` | `results[].level` | +| `finding.status` | `results[].properties.securityskills.status` | +| `finding.cwe` | `tool.driver.rules[].relationships` when supported, and `properties.securityskills.cwe` | +| `finding.framework_refs` | `tool.driver.rules[].properties.securityskills.framework_refs` | +| `finding.evidence` | `results[].locations` plus `properties.securityskills.evidence` | +| `finding.references` | `tool.driver.rules[].helpUri` or `tool.driver.rules[].properties.securityskills.references` | +| `finding.remediations` | `tool.driver.rules[].help.text` and `properties.securityskills.remediations`, including each remediation's `test_strategy` | + +## Severity + +SARIF `level` has fewer values than the normalized contract. Use this mapping: + +| Normalized severity | SARIF level | +|---|---| +| `critical` | `error` | +| `high` | `error` | +| `medium` | `warning` | +| `low` | `note` | +| `info` | `note` | + +Keep the original severity in +`results[].properties.securityskills.severity` so downstream systems can +preserve the distinction between `critical` and `high`. + +## Locations + +For source, configuration, policy, or scan-result evidence with file locations, +populate `results[].locations[].physicalLocation`: + +```json +{ + "physicalLocation": { + "artifactLocation": { + "uri": "routes/users.js" + }, + "region": { + "startLine": 42 + } + }, + "message": { + "text": "DELETE /users/:id checks authentication but not administrator role." + } +} +``` + +If the normalized evidence location does not contain a parseable file path and +line number, still emit a SARIF result and store the original location under +`properties.securityskills.evidence`. For cloud resources, identities, network +assets, logs, or documents, use the best stable asset identifier as +`artifactLocation.uri` only when it is meaningful to the SARIF consumer. + +## Rules + +Create one `tool.driver.rules[]` entry per distinct `ruleId`. A rule should +include: + +- `id`: the normalized `finding.id`, or a stable detector ID when multiple + findings share the same detection rule. +- `shortDescription.text`: the finding title or detector title. +- `fullDescription.text`: the finding description. +- `help.text`: remediation guidance and test strategy summary. +- `properties.securityskills`: CWE IDs, framework references, normalized + severity, and any remediation metadata that does not fit native SARIF fields. + +Do not invent CWE, framework, or control identifiers for SARIF. Reuse only the +values already present in the normalized finding. + +## Minimal Example + +```json +{ + "$schema": "https://json.schemastore.org/sarif-2.1.0.json", + "version": "2.1.0", + "runs": [ + { + "tool": { + "driver": { + "name": "api-security", + "semanticVersion": "1.0.0", + "rules": [ + { + "id": "API-SEC-001", + "shortDescription": { + "text": "Administrative endpoint lacks authorization check" + }, + "fullDescription": { + "text": "The delete-user route accepts authenticated requests without verifying administrative privileges." + }, + "help": { + "text": "Require an administrator role check before invoking deleteUser. Validate with integration tests for non-admin and admin delete flows." + }, + "properties": { + "securityskills": { + "severity": "high", + "cwe": ["CWE-862"], + "framework_refs": [ + { + "framework": "OWASP-API-Top-10-2023", + "control": "API5:2023", + "name": "Broken Function Level Authorization" + } + ] + } + } + } + ] + } + }, + "results": [ + { + "ruleId": "API-SEC-001", + "level": "error", + "message": { + "text": "Administrative endpoint lacks authorization check" + }, + "locations": [ + { + "physicalLocation": { + "artifactLocation": { + "uri": "routes/users.js" + }, + "region": { + "startLine": 42 + } + }, + "message": { + "text": "DELETE /users/:id checks authentication but not administrator role." + } + } + ], + "partialFingerprints": { + "securityskillsFingerprint": "api-security:users-delete:missing-admin-auth" + }, + "properties": { + "securityskills": { + "finding_id": "API-SEC-001", + "severity": "high", + "status": "open", + "remediations": [ + { + "guidance": "Require an administrator role check before invoking deleteUser.", + "confidence": "high", + "blast_radius": "User administration routes only.", + "behavior_change_risk": "medium", + "test_strategy": { + "summary": "Proves non-admin users cannot delete accounts while admins still can.", + "recommended_tests": [ + { + "name": "Reject non-admin delete", + "type": "integration", + "purpose": "Confirms the authorization bypass no longer succeeds.", + "command": "npm test -- users-authz.test.js", + "expected_result": "Non-admin DELETE returns 403 and admin DELETE succeeds." + } + ] + } + } + ] + } + } + } + ], + "properties": { + "securityskills": { + "run": { + "id": "run-001", + "timestamp": "2026-06-16T12:00:00Z", + "target": "payments-api", + "source_ref": "abc1234" + }, + "skill": { + "name": "api-security", + "version": "1.0.0", + "path": "skills/appsec/api-security/SKILL.md", + "frameworks": ["OWASP-API-Top-10-2023", "CWE"] + } + } + } + } + ] +} +``` diff --git a/skills/dependency-scanning/schemas/finding.schema.json b/skills/dependency-scanning/schemas/finding.schema.json new file mode 100644 index 0000000..535a496 --- /dev/null +++ b/skills/dependency-scanning/schemas/finding.schema.json @@ -0,0 +1,345 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/UnitOneAI/SecuritySkills/schemas/finding.schema.json", + "title": "SecuritySkills Normalized Finding Output", + "description": "Machine-readable envelope for normalized security findings and remediation recommendations emitted by SecuritySkills workflows. This contract is independent of SARIF and may be mapped to downstream enterprise formats later.", + "type": "object", + "additionalProperties": false, + "required": ["schema_version", "run", "skill", "findings"], + "properties": { + "schema_version": { + "const": "1.0.0", + "description": "Version of this normalized SecuritySkills finding envelope." + }, + "run": { + "$ref": "#/$defs/run", + "description": "Metadata for the analysis run that produced this output." + }, + "skill": { + "$ref": "#/$defs/skill", + "description": "Metadata for the SecuritySkills entrypoint that produced this output." + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/$defs/finding" + }, + "description": "Normalized findings produced by a skill run." + } + }, + "$defs": { + "riskLevel": { + "type": "string", + "enum": ["low", "medium", "high"] + }, + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "uriString": { + "type": "string", + "format": "uri" + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": ["id", "timestamp"], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable run identifier supplied by the agent, CI job, or enterprise orchestrator." + }, + "timestamp": { + "$ref": "#/$defs/nonEmptyString", + "description": "ISO 8601 timestamp for when the run output was produced." + }, + "tool": { + "$ref": "#/$defs/nonEmptyString", + "description": "Agent, CLI, scanner, or workflow that executed the skill." + }, + "target": { + "$ref": "#/$defs/nonEmptyString", + "description": "Repository, project, service, artifact, environment, or other target reviewed." + }, + "source_ref": { + "$ref": "#/$defs/nonEmptyString", + "description": "Optional commit SHA, branch, image digest, build ID, ticket ID, or evidence package reference." + } + } + }, + "skill": { + "type": "object", + "additionalProperties": false, + "required": ["name", "version"], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString", + "description": "SecuritySkills skill name from SKILL.md frontmatter." + }, + "version": { + "$ref": "#/$defs/nonEmptyString", + "description": "SecuritySkills skill version from SKILL.md frontmatter." + }, + "path": { + "$ref": "#/$defs/nonEmptyString", + "description": "Path to the SKILL.md entrypoint used for the run." + }, + "frameworks": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": "Framework identifiers declared by the skill frontmatter." + } + } + }, + "finding": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "severity", "status", "evidence", "remediations"], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable finding identifier within the output." + }, + "fingerprint": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable deduplication key based on finding type, affected asset, and evidence location." + }, + "title": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "$ref": "#/$defs/nonEmptyString", + "description": "What the issue is and why it matters." + }, + "severity": { + "type": "string", + "enum": ["info", "low", "medium", "high", "critical"] + }, + "status": { + "type": "string", + "enum": ["open", "mitigated", "accepted_risk", "false_positive"] + }, + "cwe": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "pattern": "^CWE-[0-9]+$" + }, + "description": "Optional CWE mappings, when applicable." + }, + "framework_refs": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/frameworkRef" + }, + "description": "Framework/control references from the skill frontmatter frameworks." + }, + "references": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/reference" + }, + "description": "Optional advisory, standard, vendor, or knowledge-base references." + }, + "evidence": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["location", "summary"], + "properties": { + "location": { + "$ref": "#/$defs/nonEmptyString", + "description": "File path, line range, asset ID, log source, policy path, or other concrete evidence location." + }, + "summary": { + "$ref": "#/$defs/nonEmptyString" + }, + "artifact_type": { + "type": "string", + "enum": ["source", "config", "policy", "log", "scan_result", "cloud_resource", "identity", "network", "document", "other"] + }, + "snippet": { + "$ref": "#/$defs/nonEmptyString", + "description": "Minimal redacted snippet or observation needed to support the finding." + }, + "redacted": { + "type": "boolean", + "description": "True when sensitive values were intentionally removed from this evidence." + } + } + } + }, + "remediations": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/remediation" + }, + "description": "Every fix recommendation for this finding. Each item must include remediation guidance, confidence, blast radius, behavior-change risk, and test strategy." + } + }, + "anyOf": [ + { + "required": ["cwe"] + }, + { + "required": ["framework_refs"] + } + ] + }, + "frameworkRef": { + "type": "object", + "additionalProperties": false, + "required": ["framework", "control"], + "properties": { + "framework": { + "$ref": "#/$defs/nonEmptyString" + }, + "control": { + "$ref": "#/$defs/nonEmptyString" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "reference": { + "type": "object", + "additionalProperties": false, + "required": ["type", "id"], + "properties": { + "type": { + "type": "string", + "enum": ["cve", "cwe", "framework", "advisory", "vendor", "documentation", "other"] + }, + "id": { + "$ref": "#/$defs/nonEmptyString" + }, + "url": { + "$ref": "#/$defs/uriString" + } + } + }, + "remediation": { + "type": "object", + "additionalProperties": false, + "required": ["guidance", "confidence", "blast_radius", "behavior_change_risk", "test_strategy"], + "properties": { + "guidance": { + "$ref": "#/$defs/nonEmptyString", + "description": "Concrete remediation steps or patch guidance for the finding." + }, + "confidence": { + "$ref": "#/$defs/riskLevel", + "description": "How confident the skill is that this recommendation is correct for the observed evidence." + }, + "blast_radius": { + "$ref": "#/$defs/nonEmptyString", + "description": "Expected scope of systems, files, users, integrations, data, or workflows affected by the change." + }, + "behavior_change_risk": { + "$ref": "#/$defs/riskLevel", + "description": "Risk that the remediation changes intended application or operational behavior." + }, + "test_strategy": { + "$ref": "#/$defs/testStrategy", + "description": "Required validation strategy proving the remediation fixes the finding. Include recommended tests, generated tests, or both." + } + } + }, + "testStrategy": { + "type": "object", + "additionalProperties": false, + "required": ["summary"], + "properties": { + "summary": { + "$ref": "#/$defs/nonEmptyString", + "description": "Concise explanation of what proves the remediation fixed the issue." + }, + "recommended_tests": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/recommendedTest" + }, + "description": "Tests the user or agent should run when tests are not generated directly." + }, + "generated_tests": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/generatedTest" + }, + "description": "Test files or cases produced as part of the remediation." + } + }, + "anyOf": [ + { + "required": ["recommended_tests"] + }, + { + "required": ["generated_tests"] + } + ] + }, + "recommendedTest": { + "type": "object", + "additionalProperties": false, + "required": ["name", "type", "purpose", "command", "expected_result"], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "type": { + "type": "string", + "enum": ["static", "unit", "integration", "e2e", "regression", "manual"] + }, + "purpose": { + "$ref": "#/$defs/nonEmptyString", + "description": "Behavior, vulnerability condition, or regression this test proves." + }, + "command": { + "$ref": "#/$defs/nonEmptyString", + "description": "Command or manual check to execute for this test." + }, + "expected_result": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "generatedTest": { + "type": "object", + "additionalProperties": false, + "required": ["path", "type", "purpose", "command", "expected_result"], + "properties": { + "path": { + "$ref": "#/$defs/nonEmptyString", + "description": "Path to the generated or modified test file." + }, + "type": { + "type": "string", + "enum": ["static", "unit", "integration", "e2e", "regression"] + }, + "purpose": { + "$ref": "#/$defs/nonEmptyString", + "description": "Behavior, vulnerability condition, or regression this generated test proves." + }, + "command": { + "$ref": "#/$defs/nonEmptyString", + "description": "Command that runs the generated test." + }, + "expected_result": { + "$ref": "#/$defs/nonEmptyString" + } + } + } + } +} diff --git a/skills/patch-prioritization/SKILL.md b/skills/patch-prioritization/SKILL.md index 1ae96ad..bea0687 100644 --- a/skills/patch-prioritization/SKILL.md +++ b/skills/patch-prioritization/SKILL.md @@ -381,7 +381,7 @@ Known Exploited Vulnerabilities catalog maintained by CISA. Contains CVEs with c - **Blind spots:** This skill depends on available code, configuration, logs, documentation, and user-provided context; it cannot prove controls exist or threats are absent when evidence is missing, runtime-only, or outside the review scope. - **False-positive risks:** Treat findings as hypotheses until validated against asset criticality, compensating controls, environment intent, and recent authorized changes. - **Required evidence:** Support each finding with concrete artifacts such as file paths and line numbers, policy snippets, scanner output, logs, screenshots, control records, or reproducible steps. -- **Normalized JSON:** When machine-readable output is requested, findings MUST be available as JSON that validates against [`schemas/finding.schema.json`](../../../schemas/finding.schema.json). +- **Normalized JSON:** When machine-readable output is requested, findings MUST be available as JSON that validates against [`schemas/finding.schema.json`](schemas/finding.schema.json). - **Escalation rules:** Escalate immediately for suspected active compromise, exposed secrets, regulated-data exposure, critical exploitable vulnerabilities, privileged-access abuse, or when evidence is insufficient to safely disposition a high-impact risk. --- diff --git a/skills/patch-prioritization/schemas/finding.schema.json b/skills/patch-prioritization/schemas/finding.schema.json new file mode 100644 index 0000000..535a496 --- /dev/null +++ b/skills/patch-prioritization/schemas/finding.schema.json @@ -0,0 +1,345 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/UnitOneAI/SecuritySkills/schemas/finding.schema.json", + "title": "SecuritySkills Normalized Finding Output", + "description": "Machine-readable envelope for normalized security findings and remediation recommendations emitted by SecuritySkills workflows. This contract is independent of SARIF and may be mapped to downstream enterprise formats later.", + "type": "object", + "additionalProperties": false, + "required": ["schema_version", "run", "skill", "findings"], + "properties": { + "schema_version": { + "const": "1.0.0", + "description": "Version of this normalized SecuritySkills finding envelope." + }, + "run": { + "$ref": "#/$defs/run", + "description": "Metadata for the analysis run that produced this output." + }, + "skill": { + "$ref": "#/$defs/skill", + "description": "Metadata for the SecuritySkills entrypoint that produced this output." + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/$defs/finding" + }, + "description": "Normalized findings produced by a skill run." + } + }, + "$defs": { + "riskLevel": { + "type": "string", + "enum": ["low", "medium", "high"] + }, + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "uriString": { + "type": "string", + "format": "uri" + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": ["id", "timestamp"], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable run identifier supplied by the agent, CI job, or enterprise orchestrator." + }, + "timestamp": { + "$ref": "#/$defs/nonEmptyString", + "description": "ISO 8601 timestamp for when the run output was produced." + }, + "tool": { + "$ref": "#/$defs/nonEmptyString", + "description": "Agent, CLI, scanner, or workflow that executed the skill." + }, + "target": { + "$ref": "#/$defs/nonEmptyString", + "description": "Repository, project, service, artifact, environment, or other target reviewed." + }, + "source_ref": { + "$ref": "#/$defs/nonEmptyString", + "description": "Optional commit SHA, branch, image digest, build ID, ticket ID, or evidence package reference." + } + } + }, + "skill": { + "type": "object", + "additionalProperties": false, + "required": ["name", "version"], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString", + "description": "SecuritySkills skill name from SKILL.md frontmatter." + }, + "version": { + "$ref": "#/$defs/nonEmptyString", + "description": "SecuritySkills skill version from SKILL.md frontmatter." + }, + "path": { + "$ref": "#/$defs/nonEmptyString", + "description": "Path to the SKILL.md entrypoint used for the run." + }, + "frameworks": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": "Framework identifiers declared by the skill frontmatter." + } + } + }, + "finding": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "severity", "status", "evidence", "remediations"], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable finding identifier within the output." + }, + "fingerprint": { + "$ref": "#/$defs/nonEmptyString", + "description": "Stable deduplication key based on finding type, affected asset, and evidence location." + }, + "title": { + "$ref": "#/$defs/nonEmptyString" + }, + "description": { + "$ref": "#/$defs/nonEmptyString", + "description": "What the issue is and why it matters." + }, + "severity": { + "type": "string", + "enum": ["info", "low", "medium", "high", "critical"] + }, + "status": { + "type": "string", + "enum": ["open", "mitigated", "accepted_risk", "false_positive"] + }, + "cwe": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "pattern": "^CWE-[0-9]+$" + }, + "description": "Optional CWE mappings, when applicable." + }, + "framework_refs": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/frameworkRef" + }, + "description": "Framework/control references from the skill frontmatter frameworks." + }, + "references": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/reference" + }, + "description": "Optional advisory, standard, vendor, or knowledge-base references." + }, + "evidence": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["location", "summary"], + "properties": { + "location": { + "$ref": "#/$defs/nonEmptyString", + "description": "File path, line range, asset ID, log source, policy path, or other concrete evidence location." + }, + "summary": { + "$ref": "#/$defs/nonEmptyString" + }, + "artifact_type": { + "type": "string", + "enum": ["source", "config", "policy", "log", "scan_result", "cloud_resource", "identity", "network", "document", "other"] + }, + "snippet": { + "$ref": "#/$defs/nonEmptyString", + "description": "Minimal redacted snippet or observation needed to support the finding." + }, + "redacted": { + "type": "boolean", + "description": "True when sensitive values were intentionally removed from this evidence." + } + } + } + }, + "remediations": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/remediation" + }, + "description": "Every fix recommendation for this finding. Each item must include remediation guidance, confidence, blast radius, behavior-change risk, and test strategy." + } + }, + "anyOf": [ + { + "required": ["cwe"] + }, + { + "required": ["framework_refs"] + } + ] + }, + "frameworkRef": { + "type": "object", + "additionalProperties": false, + "required": ["framework", "control"], + "properties": { + "framework": { + "$ref": "#/$defs/nonEmptyString" + }, + "control": { + "$ref": "#/$defs/nonEmptyString" + }, + "name": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "reference": { + "type": "object", + "additionalProperties": false, + "required": ["type", "id"], + "properties": { + "type": { + "type": "string", + "enum": ["cve", "cwe", "framework", "advisory", "vendor", "documentation", "other"] + }, + "id": { + "$ref": "#/$defs/nonEmptyString" + }, + "url": { + "$ref": "#/$defs/uriString" + } + } + }, + "remediation": { + "type": "object", + "additionalProperties": false, + "required": ["guidance", "confidence", "blast_radius", "behavior_change_risk", "test_strategy"], + "properties": { + "guidance": { + "$ref": "#/$defs/nonEmptyString", + "description": "Concrete remediation steps or patch guidance for the finding." + }, + "confidence": { + "$ref": "#/$defs/riskLevel", + "description": "How confident the skill is that this recommendation is correct for the observed evidence." + }, + "blast_radius": { + "$ref": "#/$defs/nonEmptyString", + "description": "Expected scope of systems, files, users, integrations, data, or workflows affected by the change." + }, + "behavior_change_risk": { + "$ref": "#/$defs/riskLevel", + "description": "Risk that the remediation changes intended application or operational behavior." + }, + "test_strategy": { + "$ref": "#/$defs/testStrategy", + "description": "Required validation strategy proving the remediation fixes the finding. Include recommended tests, generated tests, or both." + } + } + }, + "testStrategy": { + "type": "object", + "additionalProperties": false, + "required": ["summary"], + "properties": { + "summary": { + "$ref": "#/$defs/nonEmptyString", + "description": "Concise explanation of what proves the remediation fixed the issue." + }, + "recommended_tests": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/recommendedTest" + }, + "description": "Tests the user or agent should run when tests are not generated directly." + }, + "generated_tests": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/generatedTest" + }, + "description": "Test files or cases produced as part of the remediation." + } + }, + "anyOf": [ + { + "required": ["recommended_tests"] + }, + { + "required": ["generated_tests"] + } + ] + }, + "recommendedTest": { + "type": "object", + "additionalProperties": false, + "required": ["name", "type", "purpose", "command", "expected_result"], + "properties": { + "name": { + "$ref": "#/$defs/nonEmptyString" + }, + "type": { + "type": "string", + "enum": ["static", "unit", "integration", "e2e", "regression", "manual"] + }, + "purpose": { + "$ref": "#/$defs/nonEmptyString", + "description": "Behavior, vulnerability condition, or regression this test proves." + }, + "command": { + "$ref": "#/$defs/nonEmptyString", + "description": "Command or manual check to execute for this test." + }, + "expected_result": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "generatedTest": { + "type": "object", + "additionalProperties": false, + "required": ["path", "type", "purpose", "command", "expected_result"], + "properties": { + "path": { + "$ref": "#/$defs/nonEmptyString", + "description": "Path to the generated or modified test file." + }, + "type": { + "type": "string", + "enum": ["static", "unit", "integration", "e2e", "regression"] + }, + "purpose": { + "$ref": "#/$defs/nonEmptyString", + "description": "Behavior, vulnerability condition, or regression this generated test proves." + }, + "command": { + "$ref": "#/$defs/nonEmptyString", + "description": "Command that runs the generated test." + }, + "expected_result": { + "$ref": "#/$defs/nonEmptyString" + } + } + } + } +} diff --git a/skills/safedeps/SKILL.md b/skills/safedeps/SKILL.md index 7a1c23e..a9efb8b 100644 --- a/skills/safedeps/SKILL.md +++ b/skills/safedeps/SKILL.md @@ -23,12 +23,12 @@ one, run the checker and use its real output instead of your own recollection of which versions are safe. ```bash -python3 /../../check_deps.py @: -python3 /../../check_deps.py path/to/requirements.txt +python3 /check_deps.py @: +python3 /check_deps.py path/to/requirements.txt ``` -(`` is this file's directory; the script lives at the repo/plugin -root as `check_deps.py`. Ecosystems: `npm`, `PyPI`, `Go`, `crates.io`, +(`` is this file's directory; the script is vendored next to this +file, as `check_deps.py`. Ecosystems: `npm`, `PyPI`, `Go`, `crates.io`, `Maven`, etc. -- omit `:ecosystem` and it defaults to `npm`.) The script prints one of two things per package, straight from OSV.dev: @@ -42,6 +42,11 @@ VULN npm:lodash@4.17.21 -- 2 advisory(ies): ## What to do with the output +Exit code is `0` when every package is clean, `1` when at least one advisory +was found, and `2` when OSV.dev was unreachable -- `1` is a finding, not a +crash. (The manifest mode only accepts files named `requirements.txt`, +`package.json`, `package-lock.json` or `go.mod`.) + 1. If a package you're about to add/bump shows `VULN`, do not use that version. Use the version named in `fix:` instead (or newer). 2. If no fixed version is listed, tell the user there's an open advisory diff --git a/skills/sca-audit/plays/sca-audit.md b/skills/sca-audit/plays/sca-audit.md new file mode 100644 index 0000000..4d35969 --- /dev/null +++ b/skills/sca-audit/plays/sca-audit.md @@ -0,0 +1,140 @@ +# Play: Software Composition Analysis Audit + +Scan project dependencies for known vulnerabilities (CVEs), produce severity-ranked findings with remediation guidance. + +## Trigger Conditions + +Use this skill when: +- Reviewing a project's dependency files (package.json, requirements.txt, go.mod, pom.xml, Gemfile, Cargo.toml, etc.) +- A user asks to check for vulnerable dependencies +- Performing a pre-deployment security review +- Triaging a Dependabot/Renovate alert + +## Inputs + +- Project root directory (must contain dependency manifests and/or lockfiles) +- (Optional) Severity threshold — minimum severity to report (default: MEDIUM) +- (Optional) Ignore list — CVEs to suppress (with documented justification) + +## Procedure + +### 1. Identify Dependency Manifests + +Scan for all dependency files in the project: + +| Ecosystem | Manifest | Lockfile | +|-----------|----------|----------| +| Node.js | package.json | package-lock.json, yarn.lock, pnpm-lock.yaml | +| Python | requirements.txt, setup.py, pyproject.toml | Pipfile.lock, poetry.lock | +| Go | go.mod | go.sum | +| Java/Kotlin | pom.xml, build.gradle | gradle.lockfile | +| Ruby | Gemfile | Gemfile.lock | +| Rust | Cargo.toml | Cargo.lock | +| .NET | *.csproj, packages.config | packages.lock.json | +| PHP | composer.json | composer.lock | + +Prefer lockfiles over manifests — they capture the exact resolved versions including transitive dependencies. + +### 2. Run Vulnerability Scan + +Use available tools in order of preference: + +1. **osv-scanner** (recommended — uses OSV.dev database, covers all ecosystems): + ```bash + osv-scanner --lockfile= --format=json + ``` + +2. **npm audit** (Node.js projects): + ```bash + npm audit --json + ``` + +3. **pip-audit** (Python projects): + ```bash + pip-audit -r requirements.txt --format=json + ``` + +4. **govulncheck** (Go projects): + ```bash + govulncheck ./... + ``` + +5. **trivy** (multi-ecosystem, container images too): + ```bash + trivy fs --format json --scanners vuln + ``` + +If no scanner is installed, **stop and ask the user to install one** rather than attempting manual analysis. Even small projects have 50+ dependencies — manually cross-referencing versions against CVE databases is not cost-effective. Recommend: +```bash +# Fastest to install, covers all ecosystems +brew install osv-scanner # or: npm install -g osv-scanner +# Node.js projects already have this +npm audit --json +``` + +For manual triage of individual packages, use the [OSV.dev vulnerability database](https://osv.dev/list) to search by package name or CVE. + +### 3. Analyze Results + +For each vulnerability found: + +1. **Determine reachability**: Is the vulnerable code path actually used by this project? + - Check import statements and usage patterns + - A vulnerability in an unused function of a dependency is lower priority +2. **Check exploitability context**: Is the vulnerability exploitable in this deployment? + - A client-side library vuln in a server-only project may not apply + - A DoS vulnerability may be less critical for internal tools +3. **Identify fix availability**: Is there a patched version? + - Check if upgrading is a minor/patch bump (low risk) or major bump (breaking changes) + - Check if the fix is in a direct dependency or requires bumping a transitive dep + +### 4. Produce Findings + +For each confirmed vulnerability, generate a finding with: +- CVE/GHSA identifier +- Affected package and version +- Fixed version (if available) +- CVSS score and severity +- Whether the vulnerable code path is reachable +- Upgrade command to fix + +### 5. Generate Dependency Health Summary + +Beyond CVEs, flag: +- **Unmaintained packages**: No commits in 2+ years, archived repos +- **Typosquatting risk**: Package names that are suspiciously similar to popular packages +- **License concerns**: Packages with no license or unexpected license changes +- **Pinning issues**: Using ranges (^, ~) instead of exact versions in production lockfiles + +## Output Format + +```markdown +## SCA Audit: [Project Name] + +### Scan Summary +- **Ecosystems**: [Node.js, Python, etc.] +- **Total dependencies**: [N direct, M transitive] +- **Scanner used**: [tool name and version] +- **Vulnerabilities found**: [X critical, Y high, Z medium, W low] + +### Critical & High Findings +[Standard finding template for each, sorted by severity] + +### Medium & Low Findings +[Condensed table format] +| Package | Version | CVE | Severity | Fixed In | Reachable? | +|---------|---------|-----|----------|----------|------------| + +### Dependency Health +[Flags for unmaintained, license, pinning issues] + +### Remediation Commands +[Exact commands to fix — e.g., `npm install package@version`] +``` + +## OWASP References + +- **A06:2021** — Vulnerable and Outdated Components +- OWASP Dependency-Check +- OWASP Software Component Verification Standard (SCVS) +- OWASP Cheat Sheet: Vulnerable Dependency Management diff --git a/skills/sca-audit/templates/finding.md b/skills/sca-audit/templates/finding.md new file mode 100644 index 0000000..65ea1a3 --- /dev/null +++ b/skills/sca-audit/templates/finding.md @@ -0,0 +1,48 @@ +# Finding Template + +Use this structure for all security findings produced by skills. + +```markdown +### [SEVERITY] Title + +- **ID**: NDC-YYYY-NNN (auto-incrementing) +- **CWE**: CWE-XXX (if applicable) +- **CVE**: CVE-YYYY-NNNNN (if applicable) +- **OpenCRE**: [CRE-ID](https://www.opencre.org/cre/CRE-ID) — requirement name (see data/opencre/) +- **OWASP Ref**: Top 10 A01, ASVS V4.1.1, MASVS-STORAGE-1, MASWE-0001, MASTG-TEST-0200, LLM01, etc. +- **Location**: file_path:line_number or component name +- **Impact**: What an attacker can achieve (1-2 sentences) +- **Evidence**: Code snippet, command output, or proof-of-concept +- **Remediation**: Specific fix with code example +- **Confidence**: HIGH | MEDIUM | LOW (how certain is this finding) +``` + +### Resolving OpenCRE Links + +When you have a CWE, look up its OpenCRE mapping via the API: + +``` +GET https://www.opencre.org/rest/v1/standard/CWE/sectionid/{cwe-number} +``` + +This returns the CRE ID and linked standards (ASVS, WSTG, NIST 800-53, cheat sheets). Include the CRE link in findings to give readers one-click access to all related standards and remediation guidance. + +Common mappings are pre-populated in `data/opencre/README.md`. + +## Severity Definitions + +| Severity | CVSS Range | Criteria | +|----------|-----------|----------| +| CRITICAL | 9.0-10.0 | Remote code execution, full system compromise, mass data breach | +| HIGH | 7.0-8.9 | Privilege escalation, significant data exposure, auth bypass | +| MEDIUM | 4.0-6.9 | Limited data exposure, requires user interaction or specific conditions | +| LOW | 0.1-3.9 | Information disclosure, minor misconfigurations | +| INFORMATIONAL | N/A | Best practice recommendations, defense-in-depth suggestions | + +## Confidence Levels + +| Level | Meaning | +|-------|---------| +| HIGH | Confirmed via code path analysis, PoC, or tool output | +| MEDIUM | Strong indicators but not fully confirmed — needs manual verification | +| LOW | Heuristic match or pattern-based — may be false positive | diff --git a/skills/secrets-scan/plays/secrets-scan.md b/skills/secrets-scan/plays/secrets-scan.md new file mode 100644 index 0000000..69ea1f6 --- /dev/null +++ b/skills/secrets-scan/plays/secrets-scan.md @@ -0,0 +1,147 @@ +# Play: Secrets Scan + +Detect hardcoded credentials, API keys, tokens, and other secrets in source code and configuration files. + +## Trigger Conditions + +Use this skill when: +- Reviewing code for leaked secrets before commit or merge +- Auditing a repository for historical secret exposure +- A user asks to check for hardcoded credentials +- Setting up pre-commit hooks for secret detection + +## Inputs + +- Repository or directory to scan +- (Optional) List of known-safe patterns to ignore (e.g., test fixtures, example placeholders) +- (Optional) Whether to scan git history or just current files + +## Procedure + +### 1. Run Automated Scanner + +Use available tools in order of preference: + +1. **trufflehog** (recommended — scans current files + git history): + ```bash + trufflehog filesystem --directory= --json + trufflehog git file:// --json # includes git history + ``` + +2. **gitleaks** (git-aware scanning): + ```bash + gitleaks detect --source= --report-format=json --report-path=results.json + ``` + +3. **detect-secrets** (Yelp's baseline-aware scanner): + ```bash + detect-secrets scan --all-files + ``` + +If no scanner is installed, proceed with manual analysis. + +### 2. Manual Pattern Analysis + +Search for these high-confidence patterns: + +#### API Keys & Tokens +| Pattern | Service | Regex Hint | +|---------|---------|-----------| +| `AKIA[0-9A-Z]{16}` | AWS Access Key ID | Exact format | +| `sk-[a-zA-Z0-9]{48}` | OpenAI API Key | Prefix match | +| `sk-ant-[a-zA-Z0-9-]{80,}` | Anthropic API Key | Prefix match | +| `ghp_[a-zA-Z0-9]{36}` | GitHub Personal Access Token | Prefix match | +| `gho_`, `ghu_`, `ghs_`, `ghr_` | GitHub OAuth/App tokens | Prefix match | +| `xoxb-`, `xoxp-`, `xoxs-` | Slack tokens | Prefix match | +| `SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}` | SendGrid API Key | Format match | +| `sk_live_`, `pk_live_`, `rk_live_` | Stripe keys | Prefix match | + +#### Credentials in Config +| Pattern | What to Look For | +|---------|-----------------| +| Connection strings | `://user:password@host` patterns | +| Password assignments | `password = "..."`, `PASSWORD: ...`, `passwd`, `secret` | +| Private keys | `-----BEGIN (RSA\|EC\|OPENSSH) PRIVATE KEY-----` | +| Certificates | PEM-encoded certificates with private key material | +| JWT secrets | `JWT_SECRET`, `TOKEN_SECRET` assignments | +| Database credentials | `DB_PASSWORD`, `MONGO_URI`, `DATABASE_URL` with embedded credentials | + +#### High-Risk File Patterns +Scan these files with extra scrutiny: +- `.env`, `.env.*` files +- `**/config/**`, `**/settings/**` +- `docker-compose*.yml` (environment sections) +- `*.tfvars`, `terraform.tfstate` +- `kubeconfig`, `*.kubeconfig` +- `credentials`, `credentials.json`, `service-account*.json` +- `.npmrc`, `.pypirc`, `pip.conf` (registry tokens) +- `**/ci/**`, `.github/workflows/**` (inline secrets) + +### 3. Contextual Analysis + +For each detected secret: + +1. **Is it real?** Filter out: + - Placeholder values (`CHANGE_ME`, `xxx`, `your-api-key-here`, ``) + - Test fixtures with known dummy values + - Documentation examples + - Base64-encoded non-secret data that matches key patterns + +2. **Is it active?** If possible: + - Check if the key format is currently valid for the service + - Look for rotation evidence (was it replaced in a later commit?) + - Check `.gitignore` — is the file supposed to be excluded? + +3. **What's the blast radius?** + - What service does this credential access? + - What permissions does it grant? + - Is it a production or development credential? + - How long has it been exposed? + +### 4. Check Preventive Controls + +Verify that the project has: +- [ ] `.gitignore` entries for sensitive files (`.env`, `*.key`, `*.pem`, tfstate, etc.) +- [ ] Pre-commit hooks for secret scanning (trufflehog, gitleaks, detect-secrets) +- [ ] CI pipeline secret scanning step +- [ ] Documentation on how to manage secrets (env vars, vault, etc.) +- [ ] `.gitleaks.toml` or equivalent allowlist config for known false positives + +## Output Format + +```markdown +## Secrets Scan: [Repository/Directory] + +### Scan Summary +- **Scanner used**: [tool or manual] +- **Scope**: Current files | Git history | Both +- **Files scanned**: [count] +- **Secrets found**: [count by category] + +### Findings +[Standard finding template for each secret, with type and blast radius] + +### Preventive Controls +| Control | Status | +|---------|--------| +| .gitignore covers sensitive files | Present/Missing | +| Pre-commit secret scanning | Present/Missing | +| CI secret scanning | Present/Missing | + +### Immediate Actions Required +[If active production secrets are found, list rotation steps] +``` + +## Important Notes + +- **Never include the actual secret value in findings.** Show a redacted version: `AKIA****EXAMPLE` +- If active production secrets are found, flag this as requiring **immediate rotation** — the secret must be assumed compromised once it's been in version control +- Historical secrets in git history remain accessible even after deletion from current files — git history rewriting or rotation is required + +## OWASP References + +- **A07:2021** — Identification and Authentication Failures +- **CWE-798** — Use of Hard-coded Credentials +- **CWE-312** — Cleartext Storage of Sensitive Information +- OWASP Cheat Sheet: Secrets Management +- OWASP WSTG-CONF-04: Review Old Backup and Unreferenced Files for Sensitive Information diff --git a/skills/secrets-scan/templates/finding.md b/skills/secrets-scan/templates/finding.md new file mode 100644 index 0000000..65ea1a3 --- /dev/null +++ b/skills/secrets-scan/templates/finding.md @@ -0,0 +1,48 @@ +# Finding Template + +Use this structure for all security findings produced by skills. + +```markdown +### [SEVERITY] Title + +- **ID**: NDC-YYYY-NNN (auto-incrementing) +- **CWE**: CWE-XXX (if applicable) +- **CVE**: CVE-YYYY-NNNNN (if applicable) +- **OpenCRE**: [CRE-ID](https://www.opencre.org/cre/CRE-ID) — requirement name (see data/opencre/) +- **OWASP Ref**: Top 10 A01, ASVS V4.1.1, MASVS-STORAGE-1, MASWE-0001, MASTG-TEST-0200, LLM01, etc. +- **Location**: file_path:line_number or component name +- **Impact**: What an attacker can achieve (1-2 sentences) +- **Evidence**: Code snippet, command output, or proof-of-concept +- **Remediation**: Specific fix with code example +- **Confidence**: HIGH | MEDIUM | LOW (how certain is this finding) +``` + +### Resolving OpenCRE Links + +When you have a CWE, look up its OpenCRE mapping via the API: + +``` +GET https://www.opencre.org/rest/v1/standard/CWE/sectionid/{cwe-number} +``` + +This returns the CRE ID and linked standards (ASVS, WSTG, NIST 800-53, cheat sheets). Include the CRE link in findings to give readers one-click access to all related standards and remediation guidance. + +Common mappings are pre-populated in `data/opencre/README.md`. + +## Severity Definitions + +| Severity | CVSS Range | Criteria | +|----------|-----------|----------| +| CRITICAL | 9.0-10.0 | Remote code execution, full system compromise, mass data breach | +| HIGH | 7.0-8.9 | Privilege escalation, significant data exposure, auth bypass | +| MEDIUM | 4.0-6.9 | Limited data exposure, requires user interaction or specific conditions | +| LOW | 0.1-3.9 | Information disclosure, minor misconfigurations | +| INFORMATIONAL | N/A | Best practice recommendations, defense-in-depth suggestions | + +## Confidence Levels + +| Level | Meaning | +|-------|---------| +| HIGH | Confirmed via code path analysis, PoC, or tool output | +| MEDIUM | Strong indicators but not fully confirmed — needs manual verification | +| LOW | Heuristic match or pattern-based — may be false positive | diff --git a/skills/web-security-review/plays/owasp-top10-web-review.md b/skills/web-security-review/plays/owasp-top10-web-review.md new file mode 100644 index 0000000..52447ce --- /dev/null +++ b/skills/web-security-review/plays/owasp-top10-web-review.md @@ -0,0 +1,374 @@ +# Play: OWASP Top 10 Web Security Review + +Review web applications against the OWASP Top 10 for Web Applications (2021), producing actionable findings with severity ratings and remediation guidance. + +## Trigger Conditions + +Use this play when: +- Auditing a web application (monolith, microservices, or serverless) +- Reviewing server-side web code for security vulnerabilities +- A user asks for an "OWASP Top 10 review" or "web security assessment" +- Assessing a web framework or CMS for security posture +- Performing a pre-deployment security review of a web app + +## Inputs + +- Web application source code (frontend and backend) +- Framework/language information (React, Django, Rails, etc.) +- Deployment context (internet-facing, internal, cloud platform) +- Authentication/authorization implementation details +- (Optional) Previous security assessments or pentest reports + +## Procedure + +### 1. Application Mapping + +Before assessing risks, understand the application: + +| Aspect | Questions | +|--------|-----------| +| **Framework** | What language/framework? (Node.js/Express, Python/Django, Ruby/Rails, Java/Spring, PHP/Laravel, etc.) | +| **Architecture** | Monolith, microservices, serverless (Lambda/Cloud Functions), SPA vs SSR? | +| **Trust Boundary** | Internet-facing, internal network, or local-only? | +| **Data Sensitivity** | Does it handle PII, credentials, financial data, health data (HIPAA)? | +| **Authentication** | Session-based, JWT, OAuth, SSO, API keys? | +| **Data Stores** | SQL database, NoSQL, cache (Redis), file storage, external APIs? | + +Document the attack surface: entry points, data flows, trust boundaries. + +### 2. Assess Each OWASP Top 10 Risk + +#### A01: Broken Access Control + +> CWE-200, CWE-201, CWE-352, CWE-639 + +**What to Look For:** + +- [ ] **Missing authorization checks** — Endpoints or functions accessible without verifying user permissions +- [ ] **IDOR (Insecure Direct Object References)** — Can User A access User B's data by changing IDs in URLs/parameters? +- [ ] **Privilege escalation** — Can regular users access admin functions? Can users elevate their own privileges? +- [ ] **Path traversal** — Can file paths include `../` to escape intended directories? +- [ ] **CORS misconfiguration** — Overly permissive CORS allowing cross-origin attacks +- [ ] **Forced browsing** — Can unauthenticated users access protected resources by guessing URLs? +- [ ] **JWT token issues** — Missing signature validation, algorithm confusion attacks +- [ ] **Broken function-level authorization** — Different auth requirements for UI vs API endpoints + +**Testing Approach:** +1. Map all endpoints requiring authentication +2. Test each without authentication (should fail) +3. Test cross-user access (User A accessing User B's resources) +4. Test privilege escalation paths (user → admin) +5. Verify authorization on every object access, not just initial authentication + +--- + +#### A02: Cryptographic Failures + +> CWE-261, CWE-296, CWE-310, CWE-319, CWE-326, CWE-327, CWE-916 + +**What to Look For:** + +- [ ] **Weak algorithms** — MD5, SHA1 for passwords; DES, RC4 for encryption; ECB mode +- [ ] **Missing TLS** — HTTP instead of HTTPS, weak TLS versions (<1.2), insecure ciphers +- [ ] **Hardcoded credentials/keys** — API keys, database passwords, encryption keys in source code +- [ ] **Improper key management** — Keys stored in version control, no key rotation, weak key generation +- [ ] **Cleartext transmission** — Sensitive data sent over unencrypted channels +- [ ] **Cleartext storage** — Passwords, tokens, or PII stored without encryption +- [ ] **Insufficient randomness** — Predictable tokens, session IDs, or nonces +- [ ] **Missing integrity checks** — Unsigned or unvalidated data that could be tampered with + +**Testing Approach:** +1. Search for hardcoded secrets using patterns (see secrets-scan.md) +2. Verify TLS configuration (certificates, protocol versions, cipher suites) +3. Check password storage (should use bcrypt, Argon2, or PBKDF2) +4. Validate encryption implementations (no custom crypto) +5. Test for sensitive data in URLs, headers, and logs + +--- + +#### A03: Injection + +> CWE-74, CWE-78, CWE-79, CWE-89, CWE-91, CWE-564, CWE-943 + +**What to Look For:** + +| Injection Type | Indicators | Impact | +|---------------|------------|---------| +| **SQL Injection** | String concatenation in SQL, `cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")`, dynamic queries | Data exfiltration, authentication bypass, RCE | +| **NoSQL Injection** | Unsanitized JSON in MongoDB queries, `$where` clauses with user input | Data manipulation, authentication bypass | +| **OS Command Injection** | `exec()`, `system()`, `subprocess.call()` with user input | Remote code execution | +| **LDAP Injection** | User input in LDAP filters without escaping | Authentication bypass, data access | +| **XSS (Cross-Site Scripting)** | User input rendered without encoding, `innerHTML`, `dangerouslySetInnerHTML`, unescaped template output | Session hijacking, credential theft, defacement | +| **SSTI (Server-Side Template Injection)** | User input in Jinja2, ERB, EJS templates | RCE, file access | +| **XPath Injection** | User input in XPath queries | XML data access | +| **Log Injection** | CRLF in log entries (`\n\r`), log forging | Log tampering, data exfiltration | +| **Header Injection** | CRLF in HTTP headers | Response splitting, XSS | + +**Testing Approach:** +1. Search for dangerous functions (concatenation, eval, exec, innerHTML) +2. Test each input field with injection payloads +3. Verify output encoding for all user-controlled data +4. Check prepared statements/parameterized queries usage +5. Validate Content Security Policy (CSP) headers for XSS mitigation + +--- + +#### A04: Insecure Design + +> CWE-73, CWE-183, CWE-209, CWE-213, CWE-235, CWE-256, CWE-257, CWE-266, CWE-269, CWE-280, CWE-434, CWE-444, CWE-501, CWE-522, CWE-697, CWE-799, CWE-807, CWE-840, CWE-841, CWE-927, CWE-1021, CWE-1173, CWE-1174, CWE-1233 + +**What to Look For:** + +- [ ] **Missing threat modeling** — No documented attack surface, trust boundaries, or threat actors +- [ ] **Business logic flaws** — Workflow bypasses (skip payment step), race conditions (TOCTOU), price manipulation +- [ ] **Insecure workflows** — Missing confirmation steps for destructive actions, no CSRF protection on state changes +- [ ] **Lack of rate limiting** — Brute force vulnerabilities on login, password reset, or sensitive operations +- [ ] **Insufficient validation** — Client-side only validation, missing server-side checks +- [ ] **Insecure defaults** — Debug mode enabled, verbose errors in production, default credentials +- [ ] **Trust without verification** — Trusting client-provided data (prices, user IDs, permissions) +- [ ] **Missing defense in depth** — Single point of failure for security controls + +**Testing Approach:** +1. Review architecture documentation for security considerations +2. Test business logic flows for bypass opportunities +3. Check for race conditions in multi-step processes +4. Verify rate limiting on sensitive endpoints +5. Ensure all validation happens server-side + +--- + +#### A05: Security Misconfiguration + +> CWE-2, CWE-11, CWE-13, CWE-15, CWE-16, CWE-209, CWE-250, CWE-260, CWE-312, CWE-497, CWE-538, CWE-540, CWE-541, CWE-547, CWE-611, CWE-614, CWE-756, CWE-942 + +**What to Look For:** + +- [ ] **Default configurations** — Default passwords, default admin accounts, sample applications deployed +- [ ] **Verbose error messages** — Stack traces, internal paths, SQL errors exposed to users +- [ ] **Missing security headers** — No `X-Content-Type-Options`, `X-Frame-Options`, `Content-Security-Policy`, `Strict-Transport-Security` +- [ ] **Unnecessary features** — Unused ports open, unnecessary services running, debug endpoints enabled +- [ ] **Directory listing** — Web servers showing directory contents +- [ ] **Outdated software** — Old framework versions, unpatched components +- [ ] **Cloud misconfigurations** — Exposed S3 buckets, open security groups, public databases +- [ ] **Missing hardening** — Default SSL/TLS settings, unnecessary HTTP methods enabled + +**Testing Approach:** +1. Review configuration files (nginx.conf, .htaccess, application.yml) +2. Check for default credentials and accounts +3. Verify security headers using tools or manual inspection +4. Test error handling (trigger errors, check responses) +5. Scan for unnecessary open ports and services +6. Check cloud configurations for public exposure + +--- + +#### A06: Vulnerable and Outdated Components + +> CWE-937, CWE-1035, CWE-1104 + +**What to Look For:** + +- [ ] **Unpatched dependencies** — Known CVEs in libraries (see sca-audit.md) +- [ ] **Unsupported software** — End-of-life frameworks, operating systems, databases +- [ ] **Missing SBOM** — No inventory of software components +- [ ] **Unused dependencies** — Dead code increasing attack surface +- [ ] **Transitive vulnerabilities** — Vulnerabilities in dependencies of dependencies +- [ ] **Supply chain risks** — Typosquatting, malicious packages, compromised dependencies + +**Testing Approach:** +1. Run SCA scanner (osv-scanner, npm audit, pip-audit) +2. Review dependency files (package.json, requirements.txt, etc.) +3. Check for end-of-life components +4. Verify dependency update processes +5. Review lockfiles for reproducible builds + +--- + +#### A07: Identification and Authentication Failures + +> CWE-287, CWE-288, CWE-290, CWE-294, CWE-295, CWE-297, CWE-300, CWE-302, CWE-304, CWE-306, CWE-307, CWE-346, CWE-384, CWE-521, CWE-613, CWE-620, CWE-640, CWE-798, CWE-940, CWE-1216 + +**What to Look For:** + +- [ ] **Weak password policy** — No minimum length, no complexity requirements, common passwords allowed +- [ ] **Credential stuffing** — No protection against automated login attempts using breached credentials +- [ ] **Brute force** — No rate limiting or account lockout on authentication endpoints +- [ ] **Session vulnerabilities** — Predictable session IDs, session fixation, missing HttpOnly/Secure flags +- [ ] **Missing MFA** — No multi-factor authentication for sensitive accounts +- [ ] **Weak session management** — Sessions don't expire, no concurrent session limits +- [ ] **Insecure password recovery** — Weak reset tokens, predictable questions, unverified email changes +- [ ] **JWT issues** — None algorithm allowed, weak signing keys, missing expiration + +**Testing Approach:** +1. Test password requirements and complexity +2. Attempt credential stuffing with known breached credentials +3. Test for brute force protection (rate limiting, CAPTCHA, lockout) +4. Analyze session handling (cookies, tokens, expiration) +5. Test password reset flows for security +6. Verify MFA implementation and bypass opportunities + +--- + +#### A08: Software and Data Integrity Failures + +> CWE-345, CWE-353, CWE-426, CWE-494, CWE-502, CWE-565, CWE-784, CWE-829, CWE-830, CWE-915 + +**What to Look For:** + +- [ ] **Insecure deserialization** — Deserializing untrusted data (Python pickle, Java ObjectInputStream, PHP unserialize) +- [ ] **Unsigned updates** — Software updates without integrity verification +- [ ] **CI/CD attacks** — Unprotected build pipelines, compromised build agents +- [ ] **Dependency confusion** — Internal packages with names matching public packages +- [ ] **Unsigned commits** — No signature verification on code commits +- [ ] **Tamper-evident logs** — No integrity protection for audit logs +- [ ] **XML external entities (XXE)** — XML parsers with external entity processing enabled + +**Testing Approach:** +1. Search for deserialization functions with user-controlled input +2. Verify update mechanisms include signature verification +3. Review CI/CD configurations for security controls +4. Check for XXE vulnerabilities in XML parsing +5. Verify integrity checks on critical data + +--- + +#### A09: Security Logging and Monitoring Failures + +> CWE-117, CWE-223, CWE-532, CWE-778, CWE-1175 + +**What to Look For:** + +- [ ] **Missing audit logs** — No logging of authentication events, access to sensitive data, or security-critical actions +- [ ] **Insufficient log detail** — Logs don't include enough context (who, what, when, where) +- [ ] **Sensitive data in logs** — Passwords, tokens, PII logged in plaintext +- [ ] **No log protection** — Logs stored without integrity checks, accessible to attackers +- [ ] **Missing monitoring** — No alerting on suspicious activity, no SIEM integration +- [ ] **Log injection** — Attackers can forge or tamper with log entries +- [ ] **No incident response** — No documented procedures for security incidents + +**Testing Approach:** +1. Review what events are logged (authentication, authorization, data access) +2. Check log format and content for sufficiency +3. Search for sensitive data in log statements +4. Verify log storage security and retention +5. Assess monitoring and alerting capabilities + +--- + +#### A10: Server-Side Request Forgery (SSRF) + +> CWE-918 + +**What to Look For:** + +- [ ] **Unvalidated URL parameters** — User-supplied URLs fetched by the server without validation +- [ ] **Internal service access** — Can attacker reach internal services (metadata endpoints, admin panels, databases)? +- [ ] **Cloud metadata endpoints** — Access to `169.254.169.254` (AWS, Azure, GCP metadata services) +- [ ] **File protocol access** — Can `file://` URLs be used to read local files? +- [ ] **Redirect following** — Server follows redirects to attacker-controlled URLs +- [ ] **DNS rebinding** — Time-of-check vs time-of-use vulnerabilities +- [ ] **URL parsing inconsistencies** — Differences between URL parsers (e.g., `@` handling) + +**Testing Approach:** +1. Identify all endpoints accepting URLs from users +2. Test for internal service access (localhost, private IPs) +3. Attempt cloud metadata endpoint access +4. Test alternative protocols (file://, gopher://, dict://) +5. Test for URL parsing bypasses (unicode, encoding, case variations) + +--- + +### 3. Framework-Specific Checks + +Apply additional checks based on detected framework: + +| Framework | Key Security Checks | +|-----------|---------------------| +| **React/Next.js** | XSS via `dangerouslySetInnerHTML`, SSRF in `getServerSideProps`, API routes without auth | +| **Angular** | XSS protection bypasses, unsafe `bypassSecurityTrustHtml`, HTTP client interceptors | +| **Vue.js** | `v-html` XSS risks, server-side rendering vulnerabilities | +| **Express.js** | Missing Helmet middleware, no rate limiting, prototype pollution | +| **Django** | `DEBUG=True`, `SECRET_KEY` exposure, raw SQL, CSRF exemptions | +| **Flask** | Jinja2 autoescape disabled, unsafe session handling, debug mode | +| **Ruby on Rails** | Mass assignment, `render` with user input, SQL fragments, weak parameters | +| **Spring Boot** | SpEL injection, actuator endpoints exposed, mass assignment, CORS issues | +| **Laravel** | Mass assignment, raw queries, debug mode, configuration exposure | +| **ASP.NET Core** | Razor XSS, insecure deserialization, missing anti-forgery tokens | + +--- + +### 4. Configuration Review + +Examine these configuration areas: + +#### Web Server Configuration +- **nginx/Apache**: Security headers, TLS settings, rate limiting, access controls +- **Reverse proxy**: Header forwarding, SSL termination, upstream validation +- **Load balancer**: Health checks, session affinity, DDoS protection + +#### Application Configuration +- **Environment-specific settings**: Debug mode, error handling, logging levels +- **Security settings**: Password policies, session timeouts, CSRF protection +- **External integrations**: API keys, webhook secrets, OAuth configs + +#### Deployment Configuration +- **Container security**: Non-root user, read-only filesystems, resource limits +- **Kubernetes**: Network policies, security contexts, RBAC +- **Cloud services**: IAM roles, security groups, encryption at rest + +--- + +### 5. Produce Findings + +For each identified vulnerability: +- Assign severity based on exploitability and impact in deployment context +- Provide concrete evidence (code locations, configuration gaps, test results) +- Propose specific remediation steps with code examples +- Rate confidence (HIGH, MEDIUM, LOW) + +--- + +## Output Format + +```markdown +## Web Security Review: [Application Name] + +### Application Overview +- **Framework**: [React/Express, Django, Rails, etc.] +- **Deployment**: [Internet-facing, internal, cloud platform] +- **Architecture**: [Monolith, microservices, serverless] +- **Authentication**: [Session-based, JWT, OAuth] + +### Risk Matrix +| OWASP Ref | Risk | Severity | Status | +|-----------|------|----------|--------| +| A01 | Broken Access Control | HIGH | Finding | +| A02 | Cryptographic Failures | MEDIUM | Finding | +| A03 | Injection | CRITICAL | Finding | +| A04 | Insecure Design | LOW | Finding | +| A05 | Security Misconfiguration | MEDIUM | Finding | +| A06 | Vulnerable Components | HIGH | Finding | +| A07 | Auth Failures | HIGH | Finding | +| A08 | Integrity Failures | N/A | N/A | +| A09 | Logging Failures | MEDIUM | Finding | +| A10 | SSRF | N/A | N/A | + +### Findings +[Standard finding template for each identified risk] + +### Positive Controls Observed +[Security controls already in place — acknowledge good practices] + +### Recommendations +[Prioritized remediation roadmap] +``` + +--- + +## OWASP References + +- **OWASP Top 10 for Web Applications (2021)** — [owasp.org/Top10](https://owasp.org/Top10/) +- **OWASP ASVS v5.0** — Application Security Verification Standard +- **OWASP Testing Guide (WSTG)** — Web Security Testing Guide +- **OWASP Cheat Sheet Series** — Language and framework-specific guidance +- **OWASP Proactive Controls** — Secure development practices diff --git a/skills/web-security-review/templates/finding.md b/skills/web-security-review/templates/finding.md new file mode 100644 index 0000000..65ea1a3 --- /dev/null +++ b/skills/web-security-review/templates/finding.md @@ -0,0 +1,48 @@ +# Finding Template + +Use this structure for all security findings produced by skills. + +```markdown +### [SEVERITY] Title + +- **ID**: NDC-YYYY-NNN (auto-incrementing) +- **CWE**: CWE-XXX (if applicable) +- **CVE**: CVE-YYYY-NNNNN (if applicable) +- **OpenCRE**: [CRE-ID](https://www.opencre.org/cre/CRE-ID) — requirement name (see data/opencre/) +- **OWASP Ref**: Top 10 A01, ASVS V4.1.1, MASVS-STORAGE-1, MASWE-0001, MASTG-TEST-0200, LLM01, etc. +- **Location**: file_path:line_number or component name +- **Impact**: What an attacker can achieve (1-2 sentences) +- **Evidence**: Code snippet, command output, or proof-of-concept +- **Remediation**: Specific fix with code example +- **Confidence**: HIGH | MEDIUM | LOW (how certain is this finding) +``` + +### Resolving OpenCRE Links + +When you have a CWE, look up its OpenCRE mapping via the API: + +``` +GET https://www.opencre.org/rest/v1/standard/CWE/sectionid/{cwe-number} +``` + +This returns the CRE ID and linked standards (ASVS, WSTG, NIST 800-53, cheat sheets). Include the CRE link in findings to give readers one-click access to all related standards and remediation guidance. + +Common mappings are pre-populated in `data/opencre/README.md`. + +## Severity Definitions + +| Severity | CVSS Range | Criteria | +|----------|-----------|----------| +| CRITICAL | 9.0-10.0 | Remote code execution, full system compromise, mass data breach | +| HIGH | 7.0-8.9 | Privilege escalation, significant data exposure, auth bypass | +| MEDIUM | 4.0-6.9 | Limited data exposure, requires user interaction or specific conditions | +| LOW | 0.1-3.9 | Information disclosure, minor misconfigurations | +| INFORMATIONAL | N/A | Best practice recommendations, defense-in-depth suggestions | + +## Confidence Levels + +| Level | Meaning | +|-------|---------| +| HIGH | Confirmed via code path analysis, PoC, or tool output | +| MEDIUM | Strong indicators but not fully confirmed — needs manual verification | +| LOW | Heuristic match or pattern-based — may be false positive |