Files

Zhongwei Li ff1f4bd119 Initial commit

2025-11-29 17:51:02 +08:00

15 KiB

Raw Blame History

Reference Document Template

This file demonstrates how to structure detailed reference material that Claude loads on-demand.

When to use this reference: Include a clear statement about when Claude should consult this document. For example: "Consult this reference when analyzing Python code for security vulnerabilities and needing detailed remediation patterns."

Document purpose: Briefly explain what this reference provides that's not in SKILL.md.

For documents >100 lines, always include a table of contents to help Claude navigate quickly.

When to Use References
Document Organization
Detailed Technical Content
Security Framework Mappings
Remediation Patterns
Advanced Configuration
Examples and Code Samples

When to Use References

Move content from SKILL.md to references/ when:

Content exceeds 100 lines - Keep SKILL.md concise
Framework-specific details - Detailed OWASP/CWE/MITRE mappings
Advanced user content - Deep technical details for expert users
Lookup-oriented content - Rule libraries, configuration matrices, comprehensive lists
Language-specific patterns - Separate files per language/framework
Historical context - Old patterns and deprecated approaches

Keep in SKILL.md:

Core workflows (top 3-5 use cases)
Decision points and branching logic
Quick start guidance
Essential security considerations

Document Organization

Structure for Long Documents

For references >100 lines:

# Title

**When to use**: Clear trigger statement
**Purpose**: What this provides

## Table of Contents
- Links to all major sections

## Quick Reference
- Key facts or commands for fast lookup

## Detailed Content
- Comprehensive information organized logically

## Framework Mappings
- OWASP, CWE, MITRE ATT&CK references

## Examples
- Code samples and patterns

Section Naming Conventions

Use imperative or declarative headings
✅ "Detecting SQL Injection" not "How to detect SQL Injection"
✅ "Common Patterns" not "These are common patterns"
Make headings searchable and specific

Detailed Technical Content

This section demonstrates the type of detailed content that belongs in references rather than SKILL.md.

Example: Comprehensive Vulnerability Detection

SQL Injection Detection Patterns

Pattern 1: String Concatenation in Queries

# Vulnerable pattern
query = "SELECT * FROM users WHERE id = " + user_id
cursor.execute(query)

# Detection criteria:
# - SQL keyword (SELECT, INSERT, UPDATE, DELETE)
# - String concatenation operator (+, f-string)
# - Variable user input (request params, form data)

# Severity: HIGH
# CWE: CWE-89
# OWASP: A03:2021 - Injection

Remediation:

# Fixed: Parameterized query
query = "SELECT * FROM users WHERE id = ?"
cursor.execute(query, (user_id,))

# OR using ORM
user = User.objects.get(id=user_id)

Pattern 2: Unsafe String Formatting

# Vulnerable patterns
query = f"SELECT * FROM users WHERE name = '{username}'"
query = "SELECT * FROM users WHERE name = '%s'" % username
query = "SELECT * FROM users WHERE name = '{}'".format(username)

# All three patterns are vulnerable to SQL injection

Cross-Site Scripting (XSS) Detection

Pattern 1: Unescaped Output in Templates

// Vulnerable: Direct HTML injection
element.innerHTML = userInput;
document.write(userInput);

// Vulnerable: React dangerouslySetInnerHTML
<div dangerouslySetInnerHTML={{__html: userComment}} />

// Detection criteria:
# - Direct DOM manipulation (innerHTML, document.write)
# - React dangerouslySetInnerHTML with user data
# - Template engines with autoescaping disabled

// Severity: HIGH
// CWE: CWE-79
// OWASP: A03:2021 - Injection

Remediation:

// Fixed: Escaped output
element.textContent = userInput;  // Auto-escapes

// Fixed: Sanitization library
import DOMPurify from 'dompurify';
const clean = DOMPurify.sanitize(userComment);
<div dangerouslySetInnerHTML={{__html: clean}} />

Security Framework Mappings

This section provides comprehensive security framework mappings for findings.

OWASP Top 10

Map security findings to OWASP Top 10 (2021) categories:

Category	Title	Common Vulnerabilities
A01:2021	Broken Access Control	Authorization bypass, privilege escalation, IDOR
A02:2021	Cryptographic Failures	Weak crypto, plaintext storage, insecure TLS
A03:2021	Injection	SQL injection, XSS, command injection, LDAP injection
A04:2021	Insecure Design	Missing security controls, threat modeling gaps
A05:2021	Security Misconfiguration	Default configs, verbose errors, unnecessary features
A06:2021	Vulnerable Components	Outdated libraries, unpatched dependencies
A07:2021	Auth & Session Failures	Weak passwords, session fixation, missing MFA
A08:2021	Software & Data Integrity	Unsigned updates, insecure CI/CD, deserialization
A09:2021	Logging & Monitoring Failures	Insufficient logging, no alerting, log injection
A10:2021	SSRF	Server-side request forgery, unvalidated redirects

Usage: When reporting findings, map to primary OWASP category and reference the identifier (e.g., "A03:2021 - Injection").

CWE Mappings

Map to relevant Common Weakness Enumeration categories for precise vulnerability classification:

Injection Vulnerabilities

CWE-78: OS Command Injection
CWE-79: Cross-site Scripting (XSS)
CWE-89: SQL Injection
CWE-90: LDAP Injection
CWE-91: XML Injection
CWE-94: Code Injection

Authentication & Authorization

CWE-287: Improper Authentication
CWE-288: Authentication Bypass Using Alternate Path
CWE-290: Authentication Bypass by Spoofing
CWE-294: Authentication Bypass by Capture-replay
CWE-306: Missing Authentication for Critical Function
CWE-307: Improper Restriction of Excessive Authentication Attempts
CWE-352: Cross-Site Request Forgery (CSRF)

Cryptographic Issues

CWE-256: Plaintext Storage of Password
CWE-259: Use of Hard-coded Password
CWE-261: Weak Encoding for Password
CWE-321: Use of Hard-coded Cryptographic Key
CWE-326: Inadequate Encryption Strength
CWE-327: Use of Broken or Risky Cryptographic Algorithm
CWE-329: Not Using a Random IV with CBC Mode
CWE-798: Use of Hard-coded Credentials

Input Validation

CWE-20: Improper Input Validation
CWE-73: External Control of File Name or Path
CWE-434: Unrestricted Upload of File with Dangerous Type
CWE-601: URL Redirection to Untrusted Site

Sensitive Data Exposure

CWE-200: Information Exposure
CWE-209: Information Exposure Through Error Message
CWE-312: Cleartext Storage of Sensitive Information
CWE-319: Cleartext Transmission of Sensitive Information
CWE-532: Information Exposure Through Log Files

Usage: Include CWE identifier in all vulnerability reports for standardized classification.

MITRE ATT&CK

Reference relevant tactics and techniques for threat context:

Initial Access (TA0001)

T1190: Exploit Public-Facing Application
T1133: External Remote Services
T1078: Valid Accounts

Execution (TA0002)

T1059: Command and Scripting Interpreter
T1203: Exploitation for Client Execution

Persistence (TA0003)

T1098: Account Manipulation
T1136: Create Account
T1505: Server Software Component

Privilege Escalation (TA0004)

T1068: Exploitation for Privilege Escalation
T1548: Abuse Elevation Control Mechanism

Defense Evasion (TA0005)

T1027: Obfuscated Files or Information
T1140: Deobfuscate/Decode Files or Information
T1562: Impair Defenses

Credential Access (TA0006)

T1110: Brute Force
T1555: Credentials from Password Stores
T1552: Unsecured Credentials

Discovery (TA0007)

T1083: File and Directory Discovery
T1046: Network Service Scanning

Collection (TA0009)

T1005: Data from Local System
T1114: Email Collection

Exfiltration (TA0010)

T1041: Exfiltration Over C2 Channel
T1567: Exfiltration Over Web Service

Usage: When identifying vulnerabilities, consider which ATT&CK techniques an attacker could use to exploit them.

Remediation Patterns

This section provides specific remediation guidance for common vulnerability types.

SQL Injection Remediation

Step 1: Identify vulnerable queries

Search for string concatenation in SQL queries
Check for f-strings or format() with SQL keywords
Review all database interaction code

Step 2: Apply parameterized queries

# Python with sqlite3
cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

# Python with psycopg2 (PostgreSQL)
cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

# Python with SQLAlchemy (ORM)
from sqlalchemy import text
result = session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id})

Step 3: Validate and sanitize input (defense in depth)

import re

# Validate input format
if not re.match(r'^\d+$', user_id):
    raise ValueError("Invalid user ID format")

# Use ORM query builders
user = User.query.filter_by(id=user_id).first()

Step 4: Implement least privilege

Database user should have minimum required permissions
Use read-only accounts for SELECT operations
Never use admin/root accounts for application queries

XSS Remediation

Step 1: Enable auto-escaping

Most modern frameworks escape by default
Ensure auto-escaping is not disabled

Step 2: Use framework-specific safe methods

// React: Use JSX (auto-escapes)
<div>{userInput}</div>

// Vue: Use template syntax (auto-escapes)
<div>{{ userInput }}</div>

// Angular: Use property binding (auto-escapes)
<div [textContent]="userInput"></div>

Step 3: Sanitize when HTML is required

import DOMPurify from 'dompurify';

// Sanitize HTML content
const clean = DOMPurify.sanitize(userHTML, {
  ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'],
  ALLOWED_ATTR: []
});

Step 4: Content Security Policy (CSP)

<!-- Add CSP header -->
Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{random}'

Advanced Configuration

This section contains detailed configuration options and tuning parameters.

Example: SAST Tool Configuration

# Advanced security scanner configuration
scanner:
  # Severity threshold
  severity_threshold: MEDIUM

  # Rule configuration
  rules:
    enabled:
      - sql-injection
      - xss
      - hardcoded-secrets
    disabled:
      - informational-only

  # False positive reduction
  confidence_threshold: HIGH
  exclude_patterns:
    - "*/test/*"
    - "*/tests/*"
    - "*/node_modules/*"
    - "*.test.js"
    - "*.spec.ts"

  # Performance tuning
  max_file_size_kb: 2048
  timeout_seconds: 300
  parallel_jobs: 4

  # Output configuration
  output_format: json
  include_code_snippets: true
  max_snippet_lines: 10

Examples and Code Samples

This section provides comprehensive code examples for various scenarios.

Example 1: Secure API Authentication

# Secure API key handling
import os
from functools import wraps
from flask import Flask, request, jsonify

app = Flask(__name__)

# Load API key from environment (never hardcode)
VALID_API_KEY = os.environ.get('API_KEY')
if not VALID_API_KEY:
    raise ValueError("API_KEY environment variable not set")

def require_api_key(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        api_key = request.headers.get('X-API-Key')

        if not api_key:
            return jsonify({'error': 'API key required'}), 401

        # Constant-time comparison to prevent timing attacks
        import hmac
        if not hmac.compare_digest(api_key, VALID_API_KEY):
            return jsonify({'error': 'Invalid API key'}), 403

        return f(*args, **kwargs)
    return decorated_function

@app.route('/api/secure-endpoint')
@require_api_key
def secure_endpoint():
    return jsonify({'message': 'Access granted'})

Example 2: Secure Password Hashing

# Secure password storage with bcrypt
import bcrypt

def hash_password(password: str) -> str:
    """Hash a password using bcrypt."""
    # Generate salt and hash password
    salt = bcrypt.gensalt(rounds=12)  # Cost factor: 12 (industry standard)
    hashed = bcrypt.hashpw(password.encode('utf-8'), salt)
    return hashed.decode('utf-8')

def verify_password(password: str, hashed: str) -> bool:
    """Verify a password against a hash."""
    return bcrypt.checkpw(
        password.encode('utf-8'),
        hashed.encode('utf-8')
    )

# Usage
stored_hash = hash_password("user_password")
is_valid = verify_password("user_password", stored_hash)  # True

Example 3: Secure File Upload

# Secure file upload with validation
import os
import magic
from werkzeug.utils import secure_filename

ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'jpeg'}
ALLOWED_MIME_TYPES = {
    'application/pdf',
    'image/png',
    'image/jpeg'
}
MAX_FILE_SIZE = 5 * 1024 * 1024  # 5 MB

def is_allowed_file(filename: str, file_content: bytes) -> bool:
    """Validate file extension and MIME type."""
    # Check extension
    if '.' not in filename:
        return False

    ext = filename.rsplit('.', 1)[1].lower()
    if ext not in ALLOWED_EXTENSIONS:
        return False

    # Check MIME type (prevent extension spoofing)
    mime = magic.from_buffer(file_content, mime=True)
    if mime not in ALLOWED_MIME_TYPES:
        return False

    return True

def handle_upload(file):
    """Securely handle file upload."""
    # Check file size
    file.seek(0, os.SEEK_END)
    size = file.tell()
    file.seek(0)

    if size > MAX_FILE_SIZE:
        raise ValueError("File too large")

    # Read content for validation
    content = file.read()
    file.seek(0)

    # Validate file type
    if not is_allowed_file(file.filename, content):
        raise ValueError("Invalid file type")

    # Sanitize filename
    filename = secure_filename(file.filename)

    # Generate unique filename to prevent overwrite attacks
    import uuid
    unique_filename = f"{uuid.uuid4()}_{filename}"

    # Save to secure location (outside web root)
    upload_path = os.path.join('/secure/uploads', unique_filename)
    file.save(upload_path)

    return unique_filename

Best Practices for Reference Documents

Start with "When to use" - Help Claude know when to load this reference
Include table of contents - For documents >100 lines
Use concrete examples - Code samples with vulnerable and fixed versions
Map to frameworks - OWASP, CWE, MITRE ATT&CK for context
Provide remediation - Don't just identify issues, show how to fix them
Organize logically - Group related content, use clear headings
Keep examples current - Use modern patterns and current framework versions
Be concise - Even in references, challenge every sentence

15 KiB Raw Blame History