Best Practices

## DWARF Spec

[10,000 lines of DWARF specification]

## Working with DWARF

Use these tools to look up what you need:

- `dwarfdump -debug-info` - Inspect debug info entries
- `readelf -wi` - Quick overview of debug sections
- `pyelftools` - Programmatic access for complex analysis

**When to use each:**
- Use `dwarfdump` for human-readable output
- Use `readelf` for quick checks
- Use `pyelftools` when you need to parse or transform data

## Why Constant-Time Matters

**The problem:** Timing variations leak secret information through:
- Cache access patterns (fast vs slow memory)
- Branch prediction (taken vs not-taken)
- Division/modulo (variable-time on most CPUs)

**Why not just optimize later:** Compiler optimizations can introduce timing leaks
even in code that was originally constant-time. You must verify assembly output.

**Trade-off:** Constant-time code is often slower. This is acceptable for crypto
where correctness matters more than performance.

## Anti-Patterns

### Early Return on Secret Comparison

❌ **Bad:**
\`\`\`c
if (secret[i] != input[i]) return 0;  // Early exit
\`\`\`

**Why it's wrong:** Exit timing reveals position of first mismatch, leaking partial
secret information. An attacker can measure timing to guess bytes one at a time.

✅ **Good:**
\`\`\`c
diff |= secret[i] ^ input[i];  // Accumulate differences
\`\`\`

**Why it's right:** All bytes are always compared. Timing is independent of where
mismatches occur.

## Mandatory Steps

You MUST complete all steps in order. Do not skip any step.

### 1) Initial Scan
Run static analysis: `semgrep --config crypto.yaml`

### 2) Manual Review
Review all findings. For each:
- [ ] Verify it's a real issue (not false positive)
- [ ] Assess severity (critical/high/medium/low)
- [ ] Document exploit scenario

### 3) Verification
For each critical finding:
- [ ] Write proof-of-concept exploit
- [ ] Verify in test environment
- [ ] Document mitigation

## Exploration Options

Choose the approach that fits your needs:

**Option A: Quick Overview**
- Scan file structure with `tree`
- Read entry points and main modules
- Review README and documentation

**Option B: Deep Dive**
- Map all dependencies
- Trace execution paths
- Analyze data flows
- Document architecture

**Option C: Targeted Search**
- Define specific questions
- Search for relevant code
- Focus on specific subsystems

## When to Use

**Concrete triggers:**
- User implements signature, encryption, or key derivation
- Code contains `/` or `%` operators on secret-derived values
- User mentions "constant-time", "timing attack", "side-channel"
- Reviewing functions named `sign`, `verify`, `encrypt`, `decrypt`

**Flowchart:**
\`\`\`
User writing crypto code? ──yes──> Use this skill
         │
         no
         │
         v
User asking about timing attacks? ──yes──> Use this skill
         │
         no
         │
         v
Skip this skill
\`\`\`

## When NOT to Use

- Non-cryptographic code (business logic, UI, etc.)
- Public data processing where timing leaks don't matter
- Code that doesn't handle secrets, keys, or authentication tokens
- High-level API usage where timing is handled by the library

## Rationalizations to Reject

These are common shortcuts that lead to missed findings:

- **"This code is internal-only"**
  - Reject: Internal attackers exist; defense in depth matters
  
- **"Performance matters more"**
  - Reject: Security is non-negotiable for cryptographic code
  
- **"The compiler will optimize it"**
  - Reject: Never rely on compiler optimizations for security properties
  
- **"It's too rare to matter"**
  - Reject: Cryptographic vulnerabilities are often systematic, not edge cases

## Quick Start

[2-3 paragraphs of core guidance]

For common scenarios, use this command:
\`\`\`bash
uv run {baseDir}/scripts/analyze.py --quick file.c
\`\`\`

## Deep Analysis

See [ADVANCED.md](references/ADVANCED.md) for:
- Cross-architecture testing
- Custom rule development
- Integration with CI/CD
- False positive reduction

## Language-Specific Guides

- [C/C++](references/compiled.md)
- [Python](references/python.md)
- [JavaScript](references/javascript.md)

skills/
  my-skill/
    SKILL.md              # < 500 lines: overview + quick start
    references/
      ADVANCED.md         # Detailed usage
      API.md              # Complete API reference
      TROUBLESHOOTING.md  # Common issues
    workflows/
      audit-workflow.md   # Step-by-step audit process
      review-workflow.md  # Code review process
    scripts/
      analyze.py          # Analysis script
      report.py           # Report generator

#!/bin/bash
# Fast: shell + jq
command=$(echo "$1" | jq -r '.command')
if [[ ! "$command" =~ ^python[0-9.]* ]]; then
    exit 0  # Fast path: most commands exit immediately
fi
# Only analyze python commands

#!/bin/bash
command=$(echo "$1" | jq -r '.command')

# Fast-fail: most invocations exit here (instant)
if [[ ! "$command" =~ git|rm|mv ]]; then
    exit 0
fi

# Only proceed for dangerous commands

# Fast but has false positives
if [[ "$command" =~ python.*\.py ]]; then
    # Analyze
fi

# vs.

# Slow but precise
python -c "import tree_sitter; ..." # Parse AST

# Skip diagnostic commands
if [[ "$command" =~ ^(which|type|command\ -v) ]]; then
    exit 0
fi

# Skip search tools
if [[ "$command" =~ ^(grep|rg|ag|ack) ]]; then
    exit 0
fi

# Skip file operations with dangerous terms in filenames
if [[ "$command" =~ (cat|less|head|tail).*python ]]; then
    exit 0
fi

## Performance Considerations

This hook uses regex instead of AST parsing to minimize latency on every Bash command.

**Trade-off:** May have false positives on edge cases like `grep "def " python.txt`,
but Claude can rephrase. The ~100ms latency reduction is worth it.

**Tested:** No false positives in normal development workflows.

## Choosing Analysis Depth

**Quick scan** - Use when:
- Initial code review
- Unfamiliar codebase exploration
- Time constraints

**Deep analysis** - Use when:
- Security audit
- Pre-deployment verification
- Critical infrastructure

**Trade-off:** Deep analysis takes 10x longer but finds 3x more issues.