codebase-discovery

What this skill does

# Codebase Security Discovery

Generate a security-focused DISCOVERY.md for the codebase at $ARGUMENTS.

## When to Use This Skill

- Security assessment of a new codebase
- Threat modeling preparation
- Security-focused code review
- Compliance audit preparation

## Workflow Steps

1. **Discover** - Run file discovery commands at $ARGUMENTS
2. **Analyze** - Examine auth, crypto, validation patterns
3. **Map** - Identify trust boundaries and entry points
4. **Document** - Generate DISCOVERY.md using template below
5. **Verify** - Complete generation checklist

## Discovery Commands

### Security-Relevant Files

```bash
# Find security-critical files
find $ARGUMENTS -type f \( \
  -name "auth*" -o -name "*login*" -o -name "*session*" -o \
  -name "*crypt*" -o -name "*secret*" -o -name "*key*" -o \
  -name "*token*" -o -name "*password*" -o -name "*credential*" -o \
  -name "*.pem" -o -name "*.key" -o -name "*.cert" -o \
  -name "*security*" -o -name "*permission*" -o -name "*role*" -o \
  -name "*sanitiz*" -o -name "*valid*" -o -name "*filter*" \
\) 2>/dev/null | grep -v node_modules | grep -v __pycache__

# Configuration with potential secrets
find $ARGUMENTS -type f \( -name "*.env*" -o -name "*config*" -o -name "*settings*" \) 2>/dev/null | head -20

# API endpoints
grep -r -l "route\|router\|endpoint\|@app\.\|@api\." --include="*.py" --include="*.js" --include="*.ts" --include="*.go" $ARGUMENTS 2>/dev/null | head -20
```

### Analysis Targets

| Area | What to Examine |
|------|-----------------|
| **Dependencies** | Vulnerable packages, outdated versions, unnecessary deps |
| **Trust Boundaries** | HTTP endpoints, file uploads, CLI args, env vars, DB queries, message queues |
| **Auth Flow** | Identity verification, session management, token handling, permission checks, RBAC |

## Security-Enhanced Structure (Based on Claude.md)

```markdown
# [Project Name] - Security Review Documentation

## Overview
Brief description with security context: what the application does, what sensitive data it handles, and its exposure (internal/external/public).

## Technology Stack
- **Language(s)**: [With versions - check for EOL/vulnerable versions]
- **Framework(s)**: [Note known security features/issues]
- **Database**: [Type, version, connection method]
- **Authentication**: [Mechanism used]
- **Cryptographic Libraries**: [Libraries handling crypto operations]

## Security Posture Summary

| Aspect | Status | Notes |
|--------|--------|-------|
| Authentication | [Mechanism] | [Implementation location] |
| Authorization | [RBAC/ABAC/etc.] | [Where enforced] |
| Input Validation | [Centralized/Distributed] | [Key locations] |
| Output Encoding | [Present/Absent] | [Implementation] |
| Cryptography | [Libraries used] | [Algorithms observed] |
| Logging/Audit | [Present/Absent] | [What's logged] |
| Error Handling | [Secure/Leaky] | [Pattern used] |

## Project Structure (Security View)

```

project-root/
├── src/
│   ├── auth/           # [!] Authentication logic
│   ├── middleware/     # [!] Security middleware, validators
│   ├── controllers/    # [!] Input handling, business logic
│   ├── models/         # [!] Data models, ORM queries
│   ├── services/       # External integrations
│   └── utils/
│       ├── crypto.js   # [!] Cryptographic operations
│       └── sanitize.js # [!] Input sanitization
├── config/             # [!] Configuration, potential secrets
└── tests/
    └── security/       # Security-specific tests (if any)

```
[!] = Security-critical directories

## Trust Boundaries

### External Entry Points
| Entry Point | Location | Input Type | Validation |
|-------------|----------|------------|------------|
| REST API | `src/routes/api/` | JSON | [Describe] |
| File Upload | `src/controllers/upload.js` | Multipart | [Describe] |
| WebSocket | `src/ws/handler.js` | Messages | [Describe] |
| GraphQL | `src/graphql/resolvers/` | Queries | [Describe] |

### Internal Trust Boundaries
- **Service-to-Service**: How internal services authenticate
- **Database Access**: Connection handling, query construction
- **Cache Layer**: What's cached, cache poisoning risks
- **Message Queue**: Message validation, serialization

## Attack Surface

### Network Exposure
- **Public Endpoints**: Unauthenticated routes
- **Authenticated Endpoints**: Routes requiring auth
- **Admin Endpoints**: Privileged routes
- **Internal APIs**: Service-to-service communication

### Data Input Vectors
1. **User Input**: Forms, query params, headers
2. **File Input**: Uploads, imports
3. **API Input**: Third-party webhooks, callbacks
4. **Scheduled Input**: Cron jobs, background tasks

## Authentication Flow

### Primary Authentication
```

[Diagram or step-by-step flow]

1. User submits credentials to POST /auth/login
2. Server validates against [user store]
3. [Session/Token] created and returned
4. Subsequent requests authenticated via [header/cookie]

```

**Implementation Files:**
- Login handler: `src/auth/login.js`
- Session management: `src/auth/session.js`
- Auth middleware: `src/middleware/authenticate.js`

### Session Management
- **Type**: [Cookie/JWT/Session ID]
- **Storage**: [Server-side/Client-side]
- **Expiration**: [Duration, renewal policy]
- **Invalidation**: [Logout handling]

### Multi-Factor Authentication
- **Supported**: [Yes/No]
- **Implementation**: [Location if present]

## Authorization Model

### Access Control Type
[RBAC/ABAC/ACL/Custom] implemented in `path/to/authz`

### Roles & Permissions
| Role | Permissions | Definition Location |
|------|-------------|---------------------|
| admin | Full access | `src/config/roles.js` |
| user | Read, write own | `src/config/roles.js` |
| guest | Read public | `src/config/roles.js` |

### Authorization Enforcement Points
- **Route level**: `src/middleware/authorize.js`
- **Controller level**: [If present]
- **Data level**: [Row-level security if present]

## Sensitive Data Handling

### Data Classification
| Data Type | Classification | Storage | Encryption |
|-----------|---------------|---------|------------|
| Passwords | Critical | DB (hashed) | [Algorithm] |
| PII | Sensitive | DB | [At-rest encryption] |
| API Keys | Critical | Env/Vault | [Method] |
| Session Tokens | Sensitive | [Redis/Memory] | [Method] |

### Data Flow
```

[Input] → [Validation] → [Processing] → [Storage]
                ↓
         [Logging - what's logged?]

```

### Secrets Management
- **Location**: Environment variables / Vault / Config files
- **Rotation**: [Policy if any]
- **Access**: [Who/what can access]

## Cryptographic Implementation

### Algorithms in Use
| Purpose | Algorithm | Location | Assessment |
|---------|-----------|----------|------------|
| Password Hashing | [bcrypt/argon2/etc.] | `src/auth/password.js` | [Adequate/Weak] |
| Token Signing | [HS256/RS256/etc.] | `src/auth/jwt.js` | [Adequate/Weak] |
| Data Encryption | [AES-256-GCM/etc.] | `src/utils/crypto.js` | [Adequate/Weak] |
| TLS | [Version] | Server config | [Adequate/Weak] |

### Key Management
- **Storage**: [HSM/Vault/Environment/Hardcoded(!)]
- **Rotation**: [Automated/Manual/None]
- **Derivation**: [KDF used if any]

### Cryptographic Concerns
- [ ] Hardcoded keys or IVs
- [ ] Weak algorithms (MD5, SHA1 for security, DES, RC4)
- [ ] ECB mode usage
- [ ] Predictable random number generation
- [ ] Missing integrity checks (encryption without MAC)

## Input Validation & Output Encoding

### Input Validation
| Input Source | Validation Method | Location |
|--------------|-------------------|----------|
| Query params | [Schema/Manual] | `src/middleware/validate.js` |
| Request body | [Schema/Manual] | `src/middleware/validate.js` |
| File uploads | [Type/Size/Content] | `src/controllers/upload.js` |
| Headers | [Allowlist/None] | [Location] |

### Output Encoding
| Context | Encoding Method | Location |
|---------|-----------------|----------|
| HTML | [Escaped/Template auto-escape] | `src/views/` |
| JSON | [Serializer] | [Framework default] |
|