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 for taxonomy)

1. Review best practices - Check 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 for language-specific instrumentation code (Python, JavaScript/TypeScript, Java)

1. 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

1. Include context - Log relevant data points:

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

1. 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.