igbuend 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
- Discover - Run file discovery commands at $ARGUMENTS
- Analyze - Examine auth, crypto, validation patterns
- Map - Identify trust boundaries and entry points
- Document - Generate DISCOVERY.md using template below
- Verify - Complete generation checklist
Discovery Commands
Security-Relevant Files
# 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)
# [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]
- User submits credentials to POST /auth/login
- Server validates against [user store]
- [Session/Token] created and returned
- 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] |
| SQL | [Parameterized/ORM] | `src/models/` |
| Shell | [Escaped/Avoided] | [If applicable] |
## Security Controls
### Existing Controls
- [ ] CSRF protection: [Implementation]
- [ ] Rate limiting: [Implementation]
- [ ] CORS policy: [Configuration location]
- [ ] Security headers: [Helmet/manual]
- [ ] SQL injection prevention: [ORM/parameterized]
- [ ] XSS prevention: [CSP/encoding]
- [ ] Path traversal prevention: [Method]
### Logging & Monitoring
- **Security Events Logged**: [Auth failures, access denied, etc.]
- **Log Location**: `path/to/logs` or [external service]
- **Sensitive Data in Logs**: [Yes/No - check for PII leakage]
- **Audit Trail**: [Present/Absent]
### Error Handling
- **Error Response Pattern**: [Generic/Detailed]
- **Stack Traces Exposed**: [Yes/No]
- **Error Logging**: [Implementation]
## External Integrations
| Service | Purpose | Auth Method | Data Exchanged |
|---------|---------|-------------|----------------|
| [Service] | [Purpose] | [API Key/OAuth] | [Data types] |
### Third-Party Risks
- Dependency on external services for security functions
- Data sent to third parties
- Callback/webhook handling
## Dependencies Security
### Critical Dependencies
| Package | Version | Purpose | Known Issues |
|---------|---------|---------|--------------|
| [package] | [version] | [auth/crypto/etc.] | [CVEs if any] |
### Dependency Analysis Commands
```bash
# Node.js
npm audit
# Python
pip-audit / safety check
# Go
govulncheck ./...
# Ruby
bundle audit
Security Testing
Existing Security Tests
- Location:
tests/security/or integrated - Coverage: [Auth, authz, injection, etc.]
- Automation: [CI/CD integration]
Recommended Test Areas
- Authentication bypass attempts
- Authorization boundary testing
- Input validation fuzzing
- Session management testing
- Cryptographic implementation review
Configuration Security
Security-Relevant Configuration
| Setting | Location | Current Value | Recommendation |
|---|---|---|---|
| Debug mode | config/app.js |
[true/false] | false in prod |
| Session timeout | config/auth.js |
[value] | [recommendation] |
| Password policy | config/auth.js |
[policy] | [recommendation] |
Environment Variables
| Variable | Purpose | Sensitivity |
|---|---|---|
DATABASE_URL |
DB connection | High |
JWT_SECRET |
Token signing | Critical |
API_KEY |
External service | High |
High-Risk Areas
Priority Review Targets
- [Component]: [Reason for concern]
- [Component]: [Reason for concern]
- [Component]: [Reason for concern]
Known Security Debt
- [Issue 1]: [Location, severity, notes]
- [Issue 2]: [Location, severity, notes]
Quick Reference
Security-Critical Files
| File | Contains |
|---|---|
src/auth/login.js |
Authentication logic |
src/middleware/auth.js |
Auth middleware |
src/utils/crypto.js |
Crypto operations |
config/security.js |
Security configuration |
Common Vulnerability Locations
- SQLi:
src/models/, raw query usage - XSS:
src/views/, dynamic content - SSRF:
src/services/, URL handling - Path Traversal:
src/controllers/, file operations - Deserialization:
src/utils/, object parsing
Compliance Considerations
If applicable:
- GDPR: Data subject rights implementation
- PCI-DSS: Cardholder data handling
- HIPAA: PHI protection measures
- SOC 2: Security controls mapping
## Generation Checklist
Before finalizing, verify:
- [ ] All entry points identified
- [ ] Authentication flow fully traced
- [ ] Authorization enforcement points mapped
- [ ] Sensitive data flows documented
- [ ] Cryptographic usage catalogued
- [ ] External integrations listed
- [ ] High-risk areas highlighted
- [ ] Security controls inventory complete
## Success Criteria
A complete DISCOVERY.md enables a security reviewer to:
- Understand the application's security posture in <30 minutes
- Identify all trust boundaries and entry points
- Locate security-critical code files directly
- Know what authentication/authorization mechanisms exist
- Find cryptographic implementations for review
## Output
Save as `DISCOVERY.md` in the repository root at $ARGUMENTS.