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

2. Determine event types - Classify the security events to monitor (see security_events.md for taxonomy)

3. Review best practices - Check best_practices.md for what to log and what to avoid (never log passwords, secrets, or sensitive PII)

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

5. Add instrumentation - Insert structured logging calls at key decision points:

   • Before and after authentication attempts
   • At authorization check points
   • When validation fails
   • During session lifecycle events

6. Include context - Log relevant data points:

   • User identifier
   • Timestamp (automatically added)
   • IP address
   • Resource accessed
   • Success/failure status
   • Failure reasons

7. Verify instrumentation - Ensure:

   • No sensitive data (passwords, tokens, secrets) is logged
   • Structured format (JSON) is used for machine parsing
   • Appropriate log levels are set
   • 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.