security-sensitive-path-instrumenter

Security-Sensitive Path Instrumenter

Add structured logging instrumentation to security-critical code paths for runtime monitoring of authentication, authorization, input validation, session management, and other security-relevant events.

Workflow

1. Identify security-sensitive code paths - Locate authentication, authorization, input validation, or session management code that needs instrumentation

1. Determine event types - Classify the security events to monitor (see [security_events.md](references/security_events.md) for taxonomy)

1. Review best practices - Check [best_practices.md](references/best_practices.md) for what to log and what to avoid (never log passwords, secrets, or sensitive PII)

1. Select language patterns - Use [language_patterns.md](references/language_patterns.md) for language-specific instrumentation code (Python, JavaScript/TypeScript, Java)

1. Add instrumentation - Insert structured logging calls at key decision points:
2. Before and after authentication attempts
3. At authorization check points
4. When validation fails
5. During session lifecycle events

1. Include context - Log relevant data points:
2. User identifier
3. Timestamp (automatically added)
4. IP address
5. Resource accessed
6. Success/failure status
7. Failure reasons

1. Verify instrumentation - Ensure:
2. No sensitive data (passwords, tokens, secrets) is logged
3. Structured format (JSON) is used for machine parsing
4. Appropriate log levels are set
5. Performance impact is minimal

Quick Reference

Event Categories

• Authentication: Login attempts, logout, password changes, MFA, token validation
• Authorization: Access control decisions, permission checks, RBAC evaluations
• Input Validation: Validation failures, injection detection, format violations
• Session Management: Session creation/expiration, IP changes, hijacking detection
• Sensitive Data Access: PII access, financial data, encryption key usage
• Configuration Changes: Permission changes, role assignments, security policy updates

Common Patterns

Authentication (Python/Flask):

log_security_event(
    event_type='authentication_attempt',
    username=username,
    ip_address=request.remote_addr
)

Authorization (JavaScript/Express):

logSecurityEvent('authorization_check', {
  user_id: user.id,
  resource: resourceId,
  permission: requiredPermission,
  decision: hasPermission ? 'granted' : 'denied'
});

Validation (Java/Spring):

Map<String, Object> data = new HashMap<>();
data.put("user_id", user.getId());
data.put("errors", validationErrors);
SecurityLogger.logSecurityEvent("validation_failure", data);

Helper Script

Use scripts/generate_instrumentation.py to generate code snippets:

# Generate Python authentication instrumentation
python scripts/generate_instrumentation.py python authentication

# Generate JavaScript authorization instrumentation
python scripts/generate_instrumentation.py javascript authorization

# Generate Java validation instrumentation
python scripts/generate_instrumentation.py java validation

Important Reminders

Never log:

• Passwords (plaintext or hashed)
• API keys or secrets
• Full session tokens
• Credit card numbers
• Social Security numbers
• Encryption keys

Always log:

• Event type and timestamp
• User identifier (when available)
• Success/failure status
• IP address (consider GDPR)
• Resource accessed
• Action performed

Use structured logging (JSON format) for machine parsing and analysis.