@elizaos/skills 2.0.0-alpha.3

package/skills/security-constant-time-analysis/ct_analyzer/tests/test_samples/vulnerable.ts

@@ -0,0 +1,154 @@
+/**
+ * Vulnerable TypeScript code sample for constant-time analysis testing.
+ *
+ * This file demonstrates common timing side-channel vulnerabilities in JavaScript/TypeScript:
+ * - Variable-time division operations
+ * - Timing-unsafe string comparisons
+ * - Variable-latency math operations
+ * - Predictable randomness
+ *
+ * DO NOT USE THIS CODE IN PRODUCTION - it is intentionally vulnerable.
+ */
+
+/**
+ * Vulnerable modular reduction using division.
+ * Division has data-dependent timing on most platforms.
+ */
+export function vulnerableModReduce(value: number, modulus: number): number {
+    // VULNERABLE: Division has variable-time execution
+    const quotient = Math.floor(value / modulus);
+    // VULNERABLE: Modulo has variable-time execution
+    const remainder = value % modulus;
+
+    // Use quotient to prevent dead code elimination
+    if (quotient < 0) {
+        throw new Error("Unexpected negative quotient");
+    }
+
+    return remainder;
+}
+
+/**
+ * Vulnerable token comparison using early-exit equality.
+ * This leaks timing information about how many characters match.
+ */
+export function vulnerableTokenCompare(provided: string, expected: string): boolean {
+    // VULNERABLE: === on strings may early-exit
+    return provided === expected;
+}
+
+/**
+ * Vulnerable comparison using localeCompare.
+ * localeCompare() has variable-time execution.
+ */
+export function vulnerableLocaleCompare(a: string, b: string): boolean {
+    // VULNERABLE: localeCompare has variable-time execution
+    return a.localeCompare(b) === 0;
+}
+
+/**
+ * Vulnerable string search using indexOf.
+ * indexOf() has early-terminating behavior.
+ */
+export function vulnerableStringSearch(haystack: string, needle: string): boolean {
+    // VULNERABLE: indexOf has early-terminating behavior
+    return haystack.indexOf(needle) !== -1;
+}
+
+/**
+ * Vulnerable string check using includes.
+ * includes() has early-terminating behavior.
+ */
+export function vulnerableIncludes(haystack: string, needle: string): boolean {
+    // VULNERABLE: includes has early-terminating behavior
+    return haystack.includes(needle);
+}
+
+/**
+ * Vulnerable square root calculation.
+ * Math.sqrt() has variable latency based on operand values.
+ */
+export function vulnerableSqrt(value: number): number {
+    // VULNERABLE: Math.sqrt has variable latency
+    return Math.sqrt(value);
+}
+
+/**
+ * Vulnerable power calculation.
+ * Math.pow() has variable latency based on operand values.
+ */
+export function vulnerablePow(base: number, exponent: number): number {
+    // VULNERABLE: Math.pow has variable latency
+    return Math.pow(base, exponent);
+}
+
+/**
+ * Vulnerable random number generation.
+ * Math.random() is predictable and not cryptographically secure.
+ */
+export function vulnerableRandomToken(length: number): string {
+    const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    let token = '';
+
+    for (let i = 0; i < length; i++) {
+        // VULNERABLE: Math.random is predictable
+        token += chars[Math.floor(Math.random() * chars.length)];
+    }
+
+    return token;
+}
+
+/**
+ * Vulnerable string prefix check using startsWith.
+ * startsWith() has early-terminating behavior.
+ */
+export function vulnerableStartsWith(str: string, prefix: string): boolean {
+    // VULNERABLE: startsWith has early-terminating behavior
+    return str.startsWith(prefix);
+}
+
+/**
+ * Vulnerable ML-DSA-like decompose function with division.
+ * Demonstrates the KyberSlash-style vulnerability.
+ */
+export function vulnerableDecompose(r: number, gamma2: number): { r1: number; r0: number } {
+    // VULNERABLE: Division has variable-time execution
+    let r1 = Math.floor((r + 127) / (2 * gamma2));
+
+    // VULNERABLE: Modulo has variable-time execution
+    let r0 = r % (2 * gamma2);
+
+    // Centering
+    if (r0 > gamma2) {
+        r0 -= 2 * gamma2;
+        r1 += 1;
+    }
+
+    return { r1, r0 };
+}
+
+// Test harness to prevent dead code elimination
+function runTests(): void {
+    console.log("Running vulnerable operations for testing...");
+
+    const result1 = vulnerableModReduce(12345, 97);
+    console.log(`Mod reduce: ${result1}`);
+
+    const result2 = vulnerableTokenCompare("secret123", "secret123");
+    console.log(`Token compare: ${result2}`);
+
+    const result3 = vulnerableSqrt(144);
+    console.log(`Sqrt: ${result3}`);
+
+    const result4 = vulnerablePow(2, 10);
+    console.log(`Pow: ${result4}`);
+
+    const result5 = vulnerableRandomToken(16);
+    console.log(`Token: ${result5}`);
+
+    const result6 = vulnerableDecompose(1000, 261888);
+    console.log(`Decompose: r1=${result6.r1}, r0=${result6.r0}`);
+}
+
+// Export for testing
+export { runTests };

package/skills/security-constant-time-analysis/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ct-analyzer"
+version = "0.1.0"
+description = "Constant-time assembly analyzer for detecting timing side-channel vulnerabilities"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "Scott Arciszewski", email = "opensource@trailofbits.com"}
+]
+keywords = [
+    "cryptography",
+    "security",
+    "timing-attack",
+    "side-channel",
+    "constant-time",
+    "static-analysis",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+ct-analyzer = "ct_analyzer.analyzer:main"
+
+[project.urls]
+Homepage = "https://github.com/trailofbits/skills"
+Documentation = "https://github.com/trailofbits/skills/tree/main/plugins/constant-time-analysis#readme"
+Repository = "https://github.com/trailofbits/skills.git"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ct_analyzer"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "ct_analyzer/**/*.py",
+    "ct_analyzer/tests/test_samples/*.c",
+    "ct_analyzer/tests/test_samples/*.go",
+    "ct_analyzer/tests/test_samples/*.rs",
+]

package/skills/security-constant-time-analysis/skills/constant-time-analysis/README.md

@@ -0,0 +1,90 @@
+# Constant-Time Analysis Skill
+
+A Claude Code skill that detects timing side-channel vulnerabilities in cryptographic code by analyzing assembly or bytecode output for dangerous instructions.
+
+## What This Skill Does
+
+When activated, this skill helps Claude:
+
+- **Detect timing vulnerabilities** - Identifies variable-time instructions (division, floating-point) that leak secrets through execution timing
+- **Analyze across architectures** - Tests compiled output for x86_64, ARM64, RISC-V, and other targets
+- **Support scripting languages** - Analyzes PHP, JavaScript/TypeScript, Python, and Ruby via bytecode
+- **Guide constant-time fixes** - Provides patterns for Barrett reduction, constant-time selection, and safe comparisons
+- **Integrate with CI** - Produces JSON output suitable for automated pipelines
+
+## Supported Languages
+
+| Language | Analysis Method | Reference Guide |
+|----------|-----------------|-----------------|
+| C/C++ | Assembly (gcc/clang) | [references/compiled.md](references/compiled.md) |
+| Go | Assembly (go) | [references/compiled.md](references/compiled.md) |
+| Rust | Assembly (rustc) | [references/compiled.md](references/compiled.md) |
+| PHP | Zend opcodes (VLD/OPcache) | [references/php.md](references/php.md) |
+| JavaScript | V8 bytecode (Node.js) | [references/javascript.md](references/javascript.md) |
+| TypeScript | V8 bytecode (tsc + Node.js) | [references/javascript.md](references/javascript.md) |
+| Python | CPython bytecode (dis) | [references/python.md](references/python.md) |
+| Ruby | YARV bytecode | [references/ruby.md](references/ruby.md) |
+
+## Supported Architectures (Compiled Languages)
+
+| Architecture | Division Instructions | Common Use |
+|--------------|----------------------|------------|
+| x86_64 | DIV, IDIV | Servers, desktops |
+| ARM64 | UDIV, SDIV | Mobile, Apple Silicon |
+| ARM | UDIV, SDIV | Embedded |
+| RISC-V | DIV, DIVU, REM | Emerging platforms |
+| PowerPC | DIVW, DIVD | Legacy servers |
+| s390x | D, DR, DL | Mainframes |
+| i386 | DIV, IDIV | Legacy |
+
+## File Structure
+
+```text
+skills/constant-time-analysis/
+├── SKILL.md              # Entry point - routing and quick reference
+├── README.md             # This file
+└── references/
+    ├── compiled.md       # C, C++, Go, Rust analysis
+    ├── php.md            # PHP analysis (VLD installation, opcodes)
+    ├── javascript.md     # JavaScript/TypeScript analysis
+    ├── python.md         # Python analysis (dis module)
+    └── ruby.md           # Ruby analysis (YARV)
+```
+
+The analyzer tool is located at `ct_analyzer/analyzer.py` in the plugin root.
+
+## Usage
+
+The skill activates automatically when Claude detects:
+
+- Cryptographic code implementation (encryption, signing, key derivation)
+- Questions about timing attacks or constant-time programming
+- Code handling secret keys, tokens, or cryptographic material
+- Functions with division/modulo operations on potentially secret data
+
+You can also invoke it explicitly by asking Claude to check code for timing vulnerabilities.
+
+### Example Prompts
+
+```
+"Check this crypto function for timing vulnerabilities"
+"Is this signature verification constant-time?"
+"Help me replace this division with Barrett reduction"
+"Analyze this ML-KEM implementation for KyberSlash-style issues"
+"What constant-time patterns should I use here?"
+```
+
+## Quick Reference
+
+| Vulnerability | Detection | Fix |
+|--------------|-----------|-----|
+| Secret division | DIV, IDIV, SDIV, UDIV | Barrett reduction |
+| Secret branches | JE, JNE, BEQ, BNE | Bit masking, cmov |
+| Secret comparison | Early-exit memcmp | crypto/subtle |
+| Variable-time FP | FDIV, FSQRT | Avoid in crypto |
+
+## Real-World Attacks
+
+- **KyberSlash (2023)** - Division in ML-KEM leaked keys
+- **Lucky Thirteen (2013)** - Padding timing in TLS
+- **Timing attacks on RSA** - Division in modular exponentiation

package/skills/security-constant-time-analysis/skills/constant-time-analysis/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: constant-time-analysis
+description: Detects timing side-channel vulnerabilities in cryptographic code. Use when implementing or reviewing crypto code, encountering division on secrets, secret-dependent branches, or constant-time programming questions in C, C++, Go, Rust, Swift, Java, Kotlin, C#, PHP, JavaScript, TypeScript, Python, or Ruby.
+---
+
+# Constant-Time Analysis
+
+Analyze cryptographic code to detect operations that leak secret data through execution timing variations.
+
+## When to Use
+
+```text
+User writing crypto code? ──yes──> Use this skill
+         │
+         no
+         │
+         v
+User asking about timing attacks? ──yes──> Use this skill
+         │
+         no
+         │
+         v
+Code handles secret keys/tokens? ──yes──> Use this skill
+         │
+         no
+         │
+         v
+Skip this skill
+```
+
+**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", "KyberSlash"
+- Reviewing functions named `sign`, `verify`, `encrypt`, `decrypt`, `derive_key`
+
+## 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
+
+## Language Selection
+
+Based on the file extension or language context, refer to the appropriate guide:
+
+| Language   | File Extensions                   | Guide                                                    |
+| ---------- | --------------------------------- | -------------------------------------------------------- |
+| C, C++     | `.c`, `.h`, `.cpp`, `.cc`, `.hpp` | [references/compiled.md](references/compiled.md)         |
+| Go         | `.go`                             | [references/compiled.md](references/compiled.md)         |
+| Rust       | `.rs`                             | [references/compiled.md](references/compiled.md)         |
+| Swift      | `.swift`                          | [references/swift.md](references/swift.md)               |
+| Java       | `.java`                           | [references/vm-compiled.md](references/vm-compiled.md)   |
+| Kotlin     | `.kt`, `.kts`                     | [references/kotlin.md](references/kotlin.md)             |
+| C#         | `.cs`                             | [references/vm-compiled.md](references/vm-compiled.md)   |
+| PHP        | `.php`                            | [references/php.md](references/php.md)                   |
+| JavaScript | `.js`, `.mjs`, `.cjs`             | [references/javascript.md](references/javascript.md)     |
+| TypeScript | `.ts`, `.tsx`                     | [references/javascript.md](references/javascript.md)     |
+| Python     | `.py`                             | [references/python.md](references/python.md)             |
+| Ruby       | `.rb`                             | [references/ruby.md](references/ruby.md)                 |
+
+## Quick Start
+
+```bash
+# Analyze any supported file type
+uv run {baseDir}/ct_analyzer/analyzer.py <source_file>
+
+# Include conditional branch warnings
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings <source_file>
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify' <source_file>
+
+# JSON output for CI
+uv run {baseDir}/ct_analyzer/analyzer.py --json <source_file>
+```
+
+### Native Compiled Languages Only (C, C++, Go, Rust)
+
+```bash
+# Cross-architecture testing (RECOMMENDED)
+uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.c
+uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.c
+
+# Multiple optimization levels
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.c
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O3 crypto.c
+```
+
+### VM-Compiled Languages (Java, Kotlin, C#)
+
+```bash
+# Analyze Java bytecode
+uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.java
+
+# Analyze Kotlin bytecode (Android/JVM)
+uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.kt
+
+# Analyze C# IL
+uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.cs
+```
+
+Note: Java, Kotlin, and C# compile to bytecode (JVM/CIL) that runs on a virtual machine with JIT compilation. The analyzer examines the bytecode directly, not the JIT-compiled native code. The `--arch` and `--opt-level` flags do not apply to these languages.
+
+### Swift (iOS/macOS)
+
+```bash
+# Analyze Swift for native architecture
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift
+
+# Analyze for specific architecture (iOS devices)
+uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift
+
+# Analyze with different optimization levels
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.swift
+```
+
+Note: Swift compiles to native code like C/C++/Go/Rust, so it uses assembly-level analysis and supports `--arch` and `--opt-level` flags.
+
+### Prerequisites
+
+| Language               | Requirements                                              |
+| ---------------------- | --------------------------------------------------------- |
+| C, C++, Go, Rust       | Compiler in PATH (`gcc`/`clang`, `go`, `rustc`)           |
+| Swift                  | Xcode or Swift toolchain (`swiftc` in PATH)               |
+| Java                   | JDK with `javac` and `javap` in PATH                      |
+| Kotlin                 | Kotlin compiler (`kotlinc`) + JDK (`javap`) in PATH       |
+| C#                     | .NET SDK + `ilspycmd` (`dotnet tool install -g ilspycmd`) |
+| PHP                    | PHP with VLD extension or OPcache                         |
+| JavaScript/TypeScript  | Node.js in PATH                                           |
+| Python                 | Python 3.x in PATH                                        |
+| Ruby                   | Ruby with `--dump=insns` support                          |
+
+**macOS users**: Homebrew installs Java and .NET as "keg-only". You must add them to your PATH:
+
+```bash
+# For Java (add to ~/.zshrc)
+export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"
+
+# For .NET tools (add to ~/.zshrc)
+export PATH="$HOME/.dotnet/tools:$PATH"
+```
+
+See [references/vm-compiled.md](references/vm-compiled.md) for detailed setup instructions and troubleshooting.
+
+## Quick Reference
+
+| Problem                | Detection                       | Fix                                          |
+| ---------------------- | ------------------------------- | -------------------------------------------- |
+| Division on secrets    | DIV, IDIV, SDIV, UDIV           | Barrett reduction or multiply-by-inverse     |
+| Branch on secrets      | JE, JNE, BEQ, BNE               | Constant-time selection (cmov, bit masking)  |
+| Secret comparison      | Early-exit memcmp               | Use `crypto/subtle` or constant-time compare |
+| Weak RNG               | rand(), mt_rand, Math.random    | Use crypto-secure RNG                        |
+| Table lookup by secret | Array subscript on secret index | Bit-sliced lookups                           |
+
+## Interpreting Results
+
+**PASSED** - No variable-time operations detected.
+
+**FAILED** - Dangerous instructions found. Example:
+
+```text
+[ERROR] SDIV
+  Function: decompose_vulnerable
+  Reason: SDIV has early termination optimization; execution time depends on operand values
+```
+
+## Verifying Results (Avoiding False Positives)
+
+**CRITICAL**: Not every flagged operation is a vulnerability. The tool has no data flow analysis - it flags ALL potentially dangerous operations regardless of whether they involve secrets.
+
+For each flagged violation, ask: **Does this operation's input depend on secret data?**
+
+1. **Identify the secret inputs** to the function (private keys, plaintext, signatures, tokens)
+
+2. **Trace data flow** from the flagged instruction back to inputs
+
+3. **Common false positive patterns**:
+
+   ```c
+   // FALSE POSITIVE: Division uses public constant, not secret
+   int num_blocks = data_len / 16;  // data_len is length, not content
+
+   // TRUE POSITIVE: Division involves secret-derived value
+   int32_t q = secret_coef / GAMMA2;  // secret_coef from private key
+   ```
+
+4. **Document your analysis** for each flagged item
+
+### Quick Triage Questions
+
+| Question                                          | If Yes                | If No                 |
+| ------------------------------------------------- | --------------------- | --------------------- |
+| Is the operand a compile-time constant?           | Likely false positive | Continue              |
+| Is the operand a public parameter (length, count)?| Likely false positive | Continue              |
+| Is the operand derived from key/plaintext/secret? | **TRUE POSITIVE**     | Likely false positive |
+| Can an attacker influence the operand value?      | **TRUE POSITIVE**     | Likely false positive |
+
+## Limitations
+
+1. **Static Analysis Only**: Analyzes assembly/bytecode, not runtime behavior. Cannot detect cache timing or microarchitectural side-channels.
+
+2. **No Data Flow Analysis**: Flags all dangerous operations regardless of whether they process secrets. Manual review required.
+
+3. **Compiler/Runtime Variations**: Different compilers, optimization levels, and runtime versions may produce different output.
+
+## Real-World Impact
+
+- **KyberSlash (2023)**: Division instructions in post-quantum ML-KEM implementations allowed key recovery
+- **Lucky Thirteen (2013)**: Timing differences in CBC padding validation enabled plaintext recovery
+- **RSA Timing Attacks**: Early implementations leaked private key bits through division timing
+
+## References
+
+- [Cryptocoding Guidelines](https://github.com/veorq/cryptocoding) - Defensive coding for crypto
+- [KyberSlash](https://kyberslash.cr.yp.to/) - Division timing in post-quantum crypto
+- [BearSSL Constant-Time](https://www.bearssl.org/constanttime.html) - Practical constant-time techniques

package/skills/security-constant-time-analysis/skills/constant-time-analysis/references/compiled.md

@@ -0,0 +1,129 @@
+# Constant-Time Analysis: Compiled Languages
+
+Analysis guidance for C, C++, Go, and Rust. These languages compile to native assembly, where timing side-channels are detected by scanning for variable-time CPU instructions.
+
+## Running the Analyzer
+
+```bash
+# C/C++ (default: clang, native architecture)
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.c
+
+# Go
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.go
+
+# Rust
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.rs
+
+# Cross-architecture testing (RECOMMENDED)
+uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.c
+uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.c
+
+# Multiple optimization levels
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.c
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O3 crypto.c
+
+# Include conditional branch warnings
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings crypto.c
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify|decrypt' crypto.c
+
+# CI-friendly JSON output
+uv run {baseDir}/ct_analyzer/analyzer.py --json crypto.c
+```
+
+## Supported Compilers
+
+| Language | Compiler | Flag |
+|----------|----------|------|
+| C/C++ | gcc | `--compiler gcc` |
+| C/C++ | clang (default) | `--compiler clang` |
+| Go | go | `--compiler go` |
+| Rust | rustc | `--compiler rustc` |
+
+## Supported Architectures
+
+x86_64, arm64, arm, riscv64, ppc64le, s390x, i386
+
+## Dangerous Instructions by Architecture
+
+| Architecture | Division | Floating-Point |
+|-------------|----------|----------------|
+| x86_64 | DIV, IDIV, DIVQ, IDIVQ | DIVSS, DIVSD, SQRTSS, SQRTSD |
+| ARM64 | UDIV, SDIV | FDIV, FSQRT |
+| ARM | UDIV, SDIV | VDIV, VSQRT |
+| RISC-V | DIV, DIVU, REM, REMU | FDIV.S, FDIV.D, FSQRT |
+| PowerPC | DIVW, DIVD | FDIV, FSQRT |
+| s390x | D, DR, DL, DLG, DSG | DDB, SQDB |
+
+## Constant-Time Patterns
+
+### Replace Division
+
+```c
+// VULNERABLE: Compiler emits DIV instruction
+int32_t q = a / divisor;
+
+// SAFE: Barrett reduction (precompute mu = ceil(2^32 / divisor))
+uint32_t q = (uint32_t)(((uint64_t)a * mu) >> 32);
+```
+
+### Replace Branches
+
+```c
+// VULNERABLE: Branch timing reveals secret
+if (secret) { result = a; } else { result = b; }
+
+// SAFE: Constant-time selection
+uint32_t mask = -(uint32_t)(secret != 0);
+result = (a & mask) | (b & ~mask);
+```
+
+### Replace Comparisons
+
+```c
+// VULNERABLE: memcmp returns early on mismatch
+if (memcmp(a, b, len) == 0) { ... }
+
+// SAFE: Constant-time comparison
+if (CRYPTO_memcmp(a, b, len) == 0) { ... }  // OpenSSL
+if (subtle.ConstantTimeCompare(a, b) == 1) { ... }  // Go
+```
+
+## Common Mistakes
+
+1. **Testing only one optimization level** - Compilers make different decisions at O0 vs O3. A clean O2 build may have divisions at O0.
+
+2. **Testing only one architecture** - ARM and x86 have different division behavior. Test your deployment targets.
+
+3. **Ignoring warnings** - Conditional branches on secrets are exploitable. Use `--warnings` and review each branch.
+
+4. **Assuming the tool catches everything** - This tool detects instruction-level issues only. It cannot detect:
+   - Cache timing from memory access patterns
+   - Microarchitectural attacks (Spectre, etc.)
+   - Whether flagged code actually processes secrets
+
+5. **Fixing symptoms, not causes** - If compiler introduces division, understand why. Sometimes the algorithm itself needs redesign.
+
+## Go-Specific Notes
+
+Go compiles to native code, so the analyzer builds a binary and disassembles it using `go tool objdump`. The analyzer:
+- Sets `CGO_ENABLED=0` for pure Go analysis
+- Supports cross-compilation via `GOARCH` environment variable
+- Uses `-N -l` gcflags for O0 (disable optimizations)
+
+## Rust-Specific Notes
+
+Rust uses `rustc --emit=asm` for assembly generation. The analyzer:
+- Maps optimization levels to rustc's `-C opt-level` flag
+- Supports cross-compilation via `--target` flag
+- Analyzes the emitted assembly for timing-unsafe instructions
+
+## CI Integration
+
+```yaml
+- name: Check constant-time properties
+  run: |
+    uv run ct_analyzer/analyzer.py --json src/crypto/*.c
+    # Exit code 1 = violations found
+```