@elizaos/skills 2.0.0-alpha.3

package/skills/security-claude-in-chrome-troubleshooting/skills/claude-in-chrome-troubleshooting/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: claude-in-chrome-troubleshooting
+description: Diagnose and fix Claude in Chrome MCP extension connectivity issues. Use when mcp__claude-in-chrome__* tools fail, return "Browser extension is not connected", or behave erratically.
+---
+
+# Claude in Chrome MCP Troubleshooting
+
+Use this skill when Claude in Chrome MCP tools fail to connect or work unreliably.
+
+## When to Use
+
+- `mcp__claude-in-chrome__*` tools fail with "Browser extension is not connected"
+- Browser automation works erratically or times out
+- After updating Claude Code or Claude.app
+- When switching between Claude Code CLI and Claude.app (Cowork)
+- Native host process is running but MCP tools still fail
+
+## When NOT to Use
+
+- **Linux or Windows users** - This skill covers macOS-specific paths and tools (`~/Library/Application Support/`, `osascript`)
+- General Chrome automation issues unrelated to the Claude extension
+- Claude.app desktop issues (not browser-related)
+- Network connectivity problems
+- Chrome extension installation issues (use Chrome Web Store support)
+
+## The Claude.app vs Claude Code Conflict (Primary Issue)
+
+**Background:** When Claude.app added Cowork support (browser automation from the desktop app), it introduced a competing native messaging host that conflicts with Claude Code CLI.
+
+### Two Native Hosts, Two Socket Formats
+
+| Component | Native Host Binary | Socket Location |
+|-----------|-------------------|-----------------|
+| **Claude.app (Cowork)** | `/Applications/Claude.app/Contents/Helpers/chrome-native-host` | `/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock` |
+| **Claude Code CLI** | `~/.local/share/claude/versions/<version> --chrome-native-host` | `$TMPDIR/claude-mcp-browser-bridge-$USER` (single file) |
+
+### Why They Conflict
+
+1. Both register native messaging configs in Chrome:
+   - `com.anthropic.claude_browser_extension.json` → Claude.app helper
+   - `com.anthropic.claude_code_browser_extension.json` → Claude Code wrapper
+
+2. Chrome extension requests a native host by name
+3. If the wrong config is active, the wrong binary runs
+4. The wrong binary creates sockets in a format/location the MCP client doesn't expect
+5. Result: "Browser extension is not connected" even though everything appears to be running
+
+### The Fix: Disable Claude.app's Native Host
+
+**If you use Claude Code CLI for browser automation (not Cowork):**
+
+```bash
+# Disable the Claude.app native messaging config
+mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
+   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled
+
+# Ensure the Claude Code config exists and points to the wrapper
+cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json
+```
+
+**If you use Cowork (Claude.app) for browser automation:**
+
+```bash
+# Disable the Claude Code native messaging config
+mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json \
+   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.disabled
+```
+
+**You cannot use both simultaneously.** Pick one and disable the other.
+
+### Toggle Script
+
+Add this to `~/.zshrc` or run directly:
+
+```bash
+chrome-mcp-toggle() {
+    local CONFIG_DIR=~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
+    local CLAUDE_APP="$CONFIG_DIR/com.anthropic.claude_browser_extension.json"
+    local CLAUDE_CODE="$CONFIG_DIR/com.anthropic.claude_code_browser_extension.json"
+
+    if [[ -f "$CLAUDE_APP" && ! -f "$CLAUDE_APP.disabled" ]]; then
+        # Currently using Claude.app, switch to Claude Code
+        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
+        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
+        echo "Switched to Claude Code CLI"
+        echo "Restart Chrome and Claude Code to apply"
+    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
+        # Currently using Claude Code, switch to Claude.app
+        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
+        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
+        echo "Switched to Claude.app (Cowork)"
+        echo "Restart Chrome to apply"
+    else
+        echo "Current state unclear. Check configs:"
+        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
+    fi
+}
+```
+
+Usage: `chrome-mcp-toggle` then restart Chrome (and Claude Code if switching to CLI).
+
+## Quick Diagnosis
+
+```bash
+# 1. Which native host binary is running?
+ps aux | grep chrome-native-host | grep -v grep
+# Claude.app: /Applications/Claude.app/Contents/Helpers/chrome-native-host
+# Claude Code: ~/.local/share/claude/versions/X.X.X --chrome-native-host
+
+# 2. Where is the socket?
+# For Claude Code (single file in TMPDIR):
+ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1
+
+# For Claude.app (directory with PID files):
+ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1
+
+# 3. What's the native host connected to?
+lsof -U 2>&1 | grep claude-mcp-browser-bridge
+
+# 4. Which configs are active?
+ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json
+```
+
+## Critical Insight
+
+**MCP connects at startup.** If the browser bridge wasn't ready when Claude Code started, the connection will fail for the entire session. The fix is usually: ensure Chrome + extension are running with correct config, THEN restart Claude Code.
+
+## Full Reset Procedure (Claude Code CLI)
+
+```bash
+# 1. Ensure correct config is active
+mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
+   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled 2>/dev/null
+
+# 2. Update the wrapper to use latest Claude Code version
+cat > ~/.claude/chrome/chrome-native-host << 'EOF'
+#!/bin/bash
+LATEST=$(ls -t ~/.local/share/claude/versions/ 2>/dev/null | head -1)
+exec "$HOME/.local/share/claude/versions/$LATEST" --chrome-native-host
+EOF
+chmod +x ~/.claude/chrome/chrome-native-host
+
+# 3. Kill existing native host and clean sockets
+pkill -f chrome-native-host
+rm -rf /tmp/claude-mcp-browser-bridge-$USER/
+rm -f "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
+
+# 4. Restart Chrome
+osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"
+
+# 5. Wait for Chrome, click Claude extension icon
+
+# 6. Verify correct native host is running
+ps aux | grep chrome-native-host | grep -v grep
+# Should show: ~/.local/share/claude/versions/X.X.X --chrome-native-host
+
+# 7. Verify socket exists
+ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
+
+# 8. Restart Claude Code
+```
+
+## Other Common Causes
+
+### Multiple Chrome Profiles
+
+If you have the Claude extension installed in multiple Chrome profiles, each spawns its own native host and socket. This can cause confusion.
+
+**Fix:** Only enable the Claude extension in ONE Chrome profile.
+
+### Multiple Claude Code Sessions
+
+Running multiple Claude Code instances can cause socket conflicts.
+
+**Fix:** Only run one Claude Code session at a time, or use `/mcp` to reconnect after closing other sessions.
+
+### Hardcoded Version in Wrapper
+
+The wrapper at `~/.claude/chrome/chrome-native-host` may have a hardcoded version that becomes stale after updates.
+
+**Diagnosis:**
+```bash
+cat ~/.claude/chrome/chrome-native-host
+# Bad: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
+# Good: Uses $(ls -t ...) to find latest
+```
+
+**Fix:** Use the dynamic version wrapper shown in the Full Reset Procedure above.
+
+### TMPDIR Not Set
+
+Claude Code expects `TMPDIR` to be set to find the socket.
+
+```bash
+# Check
+echo $TMPDIR
+# Should show: /var/folders/XX/.../T/
+
+# Fix: Add to ~/.zshrc
+export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"
+```
+
+## Diagnostic Deep Dive
+
+```bash
+echo "=== Native Host Binary ==="
+ps aux | grep chrome-native-host | grep -v grep
+
+echo -e "\n=== Socket (Claude Code location) ==="
+ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1
+
+echo -e "\n=== Socket (Claude.app location) ==="
+ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1
+
+echo -e "\n=== Native Host Open Files ==="
+pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"
+
+echo -e "\n=== Active Native Messaging Configs ==="
+ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null
+
+echo -e "\n=== Custom Wrapper Contents ==="
+cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No custom wrapper"
+
+echo -e "\n=== TMPDIR ==="
+echo "TMPDIR=$TMPDIR"
+echo "Expected: $(getconf DARWIN_USER_TEMP_DIR)"
+```
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `~/.claude/chrome/chrome-native-host` | Custom wrapper script for Claude Code |
+| `/Applications/Claude.app/Contents/Helpers/chrome-native-host` | Claude.app (Cowork) native host |
+| `~/.local/share/claude/versions/<version>` | Claude Code binary (run with `--chrome-native-host`) |
+| `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json` | Config for Claude.app native host |
+| `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json` | Config for Claude Code native host |
+| `$TMPDIR/claude-mcp-browser-bridge-$USER` | Socket file (Claude Code) |
+| `/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock` | Socket files (Claude.app) |
+
+## Summary
+
+1. **Primary issue:** Claude.app (Cowork) and Claude Code use different native hosts with incompatible socket formats
+2. **Fix:** Disable the native messaging config for whichever one you're NOT using
+3. **After any fix:** Must restart Chrome AND Claude Code (MCP connects at startup)
+4. **One profile:** Only have Claude extension in one Chrome profile
+5. **One session:** Only run one Claude Code instance
+
+---
+
+*Original skill by [@jeffzwang](https://github.com/jeffzwang) from [@ExaAILabs](https://github.com/ExaAILabs). Enhanced and updated for current versions of Claude Desktop and Claude Code.*

package/skills/security-constant-time-analysis/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "constant-time-analysis",
+  "version": "0.1.0",
+  "description": "Detect compiler-induced timing side-channels in cryptographic code",
+  "author": {
+    "name": "Scott Arciszewski",
+    "url": "https://github.com/trailofbits"
+  }
+}

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

@@ -0,0 +1,381 @@
+# Constant-Time Analyzer (ct-analyzer)
+
+A portable tool for detecting timing side-channel vulnerabilities in compiled cryptographic code. Analyzes assembly output from multiple compilers and architectures to detect instructions that could leak secret data through execution timing.
+
+## Background
+
+Timing side-channel attacks exploit variations in execution time to extract secret information from cryptographic implementations. Common sources include:
+
+- **Hardware division** (`DIV`, `IDIV`): Execution time varies based on operand values
+- **Floating-point operations** (`FDIV`, `FSQRT`): Variable latency based on inputs
+- **Conditional branches**: Different execution paths have different timing
+
+The infamous [KyberSlash](https://kyberslash.cr.yp.to/) attack demonstrated how division instructions in post-quantum cryptographic implementations could be exploited to recover secret keys.
+
+## Features
+
+- **Multi-language support**: C, C++, Go, Rust, PHP, JavaScript, TypeScript, Python, Ruby
+- **Multi-architecture support**: x86_64, ARM64, ARM, RISC-V, PowerPC, s390x, i386
+- **Multi-compiler support**: GCC, Clang, Go compiler, Rustc
+- **Scripting language support**: PHP (VLD/opcache), JavaScript/TypeScript (V8 bytecode), Python (dis), Ruby (YARV)
+- **Optimization-level testing**: Test across O0-O3, Os, Oz
+- **Multiple output formats**: Text, JSON, GitHub Actions annotations
+- **Cross-compilation**: Analyze code for different target architectures
+
+## Quick Start
+
+```bash
+# Install
+uv pip install -e .
+
+# Analyze a C file
+ct-analyzer crypto.c
+```
+
+## Usage
+
+### Basic Analysis
+
+```bash
+ct-analyzer <source_file>
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--arch, -a` | Target architecture (x86_64, arm64, arm, riscv64, ppc64le, s390x, i386) |
+| `--compiler, -c` | Compiler to use (gcc, clang, go, rustc) |
+| `--opt-level, -O` | Optimization level (O0, O1, O2, O3, Os, Oz) - default: O2 |
+| `--warnings, -w` | Include conditional branch warnings |
+| `--func, -f` | Regex pattern to filter functions |
+| `--json` | Output JSON format |
+| `--github` | Output GitHub Actions annotations |
+| `--list-arch` | List supported architectures |
+
+### Examples
+
+```bash
+# Test with different optimization levels
+ct-analyzer --opt-level O0 crypto.c
+ct-analyzer --opt-level O3 crypto.c
+
+# Cross-compile for ARM64
+ct-analyzer --arch arm64 crypto.c
+
+# Include conditional branch warnings
+ct-analyzer --warnings crypto.c
+
+# Analyze specific functions
+ct-analyzer --func 'decompose|sign' crypto.c
+
+# JSON output for CI
+ct-analyzer --json crypto.c
+
+# Analyze Go code
+ct-analyzer crypto.go
+
+# Analyze Rust code
+ct-analyzer crypto.rs
+
+# Analyze PHP code (requires PHP with VLD extension or opcache)
+ct-analyzer crypto.php
+
+# Analyze TypeScript (transpiles to JS first)
+ct-analyzer crypto.ts
+
+# Analyze JavaScript (uses V8 bytecode analysis)
+ct-analyzer crypto.js
+
+# Analyze Python (uses dis module for bytecode disassembly)
+ct-analyzer crypto.py
+
+# Analyze Ruby (uses YARV instruction dump)
+ct-analyzer crypto.rb
+```
+
+## Detected Vulnerabilities
+
+### Error-Level (Must Fix)
+
+| Category | x86_64 | ARM64 | RISC-V |
+|----------|--------|-------|--------|
+| Integer Division | DIV, IDIV, DIVQ, IDIVQ | UDIV, SDIV | DIV, DIVU, REM, REMU |
+| FP Division | DIVSS, DIVSD, DIVPS, DIVPD | FDIV | FDIV.S, FDIV.D |
+| Square Root | SQRTSS, SQRTSD, SQRTPS, SQRTPD | FSQRT | FSQRT.S, FSQRT.D |
+
+### Warning-Level (Review Needed)
+
+Conditional branches that may leak timing if condition depends on secret data:
+
+- x86: JE, JNE, JZ, JNZ, JA, JB, JG, JL, etc.
+- ARM: BEQ, BNE, CBZ, CBNZ, TBZ, TBNZ
+- RISC-V: BEQ, BNE, BLT, BGE
+
+## Scripting Language Support
+
+### PHP Analysis
+
+PHP analysis uses either the VLD extension (recommended) or opcache debug output:
+
+**Detected PHP Vulnerabilities:**
+
+| Category | Pattern | Recommendation |
+|----------|---------|----------------|
+| Division | `ZEND_DIV`, `ZEND_MOD` | Use Barrett reduction |
+| Cache timing | `chr()`, `ord()` | Use `pack('C', $int)` / `unpack('C', $char)[1]` |
+| Table lookups | `bin2hex()`, `hex2bin()`, `base64_encode()` | Use constant-time alternatives |
+| Array access | `FETCH_DIM_R` (secret index) | Use constant-time table lookup |
+| Bit shifts | `ZEND_SL`, `ZEND_SR` (secret amount) | Mask shift amount |
+| Variable encoding | `pack()`, `serialize()`, `json_encode()` | Use fixed-length output |
+| Weak RNG | `rand()`, `mt_rand()`, `uniqid()` | Use `random_int()` / `random_bytes()` |
+| String comparison | `strcmp()`, `===` on secrets | Use `hash_equals()` |
+
+**Installation:**
+
+```bash
+# Install VLD extension (recommended)
+# Query latest version from PECL
+VLD_VERSION=$(curl -s https://pecl.php.net/package/vld | grep -oP 'vld-\K[0-9.]+(?=\.tgz)' | head -1)
+pecl install channel://pecl.php.net/vld-${VLD_VERSION}
+
+# Or build from source (if PECL fails)
+git clone https://github.com/derickr/vld.git && cd vld
+phpize && ./configure && make && sudo make install
+
+# Or use opcache (built-in, fallback)
+# Enabled by default in PHP 7+
+```
+
+### JavaScript/TypeScript Analysis
+
+JavaScript analysis uses V8 bytecode via Node.js `--print-bytecode`. TypeScript files are automatically transpiled first.
+
+**Detected JS Vulnerabilities:**
+
+| Category | Pattern | Recommendation |
+|----------|---------|----------------|
+| Division | `Div`, `Mod` bytecodes | Use constant-time multiply-shift |
+| Array access | `LdaKeyedProperty` (secret index) | Use constant-time table lookup |
+| Bit shifts | `ShiftLeft`, `ShiftRight` (secret amount) | Mask shift amount |
+| Variable encoding | `TextEncoder`, `JSON.stringify()`, `btoa()` | Use fixed-length output |
+| Weak RNG | `Math.random()` | Use `crypto.getRandomValues()` or `crypto.randomBytes()` |
+| Variable latency | `Math.sqrt()`, `Math.pow()` | Avoid in crypto paths |
+| String comparison | `===` on secrets | Use `crypto.timingSafeEqual()` (Node.js) |
+| Early-exit search | `indexOf()`, `includes()` | Use constant-time comparison |
+
+**Requirements:**
+```bash
+# Node.js required
+node --version
+
+# TypeScript compiler (optional, for .ts files)
+npm install -g typescript
+```
+
+### Python Analysis
+
+Python analysis uses the built-in `dis` module to analyze CPython bytecode.
+
+**Detected Python Vulnerabilities:**
+
+| Category | Pattern | Recommendation |
+|----------|---------|----------------|
+| Division | `BINARY_OP 11 (/)`, `BINARY_OP 6 (%)` | Use Barrett reduction or constant-time alternatives |
+| Array access | `BINARY_SUBSCR` (secret index) | Use constant-time table lookup |
+| Bit shifts | `BINARY_LSHIFT`, `BINARY_RSHIFT` (secret amount) | Mask shift amount |
+| Variable encoding | `int.to_bytes()`, `json.dumps()`, `base64.b64encode()` | Use fixed-length output |
+| Weak RNG | `random.random()`, `random.randint()` | Use `secrets.token_bytes()` / `secrets.randbelow()` |
+| Variable latency | `math.sqrt()`, `math.pow()` | Avoid in crypto paths |
+| String comparison | `==` on secrets | Use `hmac.compare_digest()` |
+| Early-exit search | `.find()`, `.startswith()` | Use constant-time comparison |
+
+**Requirements:**
+```bash
+# Python 3.x required (built-in dis module)
+python3 --version
+```
+
+### Ruby Analysis
+
+Ruby analysis uses YARV (Yet Another Ruby VM) bytecode via `ruby --dump=insns`.
+
+**Detected Ruby Vulnerabilities:**
+
+| Category | Pattern | Recommendation |
+|----------|---------|----------------|
+| Division | `opt_div`, `opt_mod` | Use constant-time alternatives |
+| Array access | `opt_aref` (secret index) | Use constant-time table lookup |
+| Bit shifts | `opt_lshift`, `opt_rshift` (secret amount) | Mask shift amount |
+| Variable encoding | `pack()`, `to_json()`, `Base64.encode64()` | Use fixed-length output |
+| Weak RNG | `rand()`, `Random.new` | Use `SecureRandom.random_bytes()` |
+| Variable latency | `Math.sqrt()` | Avoid in crypto paths |
+| String comparison | `==` on secrets | Use `Rack::Utils.secure_compare()` or OpenSSL |
+| Early-exit search | `.include?()`, `.start_with?()` | Use constant-time comparison |
+
+**Requirements:**
+```bash
+# Ruby required (YARV is standard since Ruby 1.9)
+ruby --version
+```
+
+## Example Output
+
+```text
+============================================================
+Constant-Time Analysis Report
+============================================================
+Source: decompose.c
+Architecture: arm64
+Compiler: clang
+Optimization: O2
+Functions analyzed: 4
+Instructions analyzed: 88
+
+VIOLATIONS FOUND:
+----------------------------------------
+[ERROR] SDIV
+  Function: decompose_vulnerable
+  Reason: SDIV has early termination optimization; execution time depends on operand values
+
+[ERROR] SDIV
+  Function: use_hint_vulnerable
+  Reason: SDIV has early termination optimization; execution time depends on operand values
+
+----------------------------------------
+Result: FAILED
+Errors: 2, Warnings: 0
+```
+
+## Fixing Violations
+
+### Replace Division with Barrett Reduction
+
+```c
+// VULNERABLE
+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 with Constant-Time Selection
+
+```c
+// VULNERABLE
+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
+if (memcmp(a, b, len) == 0) { ... }
+
+// SAFE: Use crypto/subtle or equivalent
+if (subtle.ConstantTimeCompare(a, b) == 1) { ... }
+```
+
+## Test Samples
+
+The repository includes test samples demonstrating vulnerable and secure implementations:
+
+- `ct_analyzer/tests/test_samples/decompose_vulnerable.c` - Vulnerable C implementation
+- `ct_analyzer/tests/test_samples/decompose_constant_time.c` - Constant-time C implementation
+- `ct_analyzer/tests/test_samples/decompose_vulnerable.go` - Vulnerable Go implementation
+- `ct_analyzer/tests/test_samples/decompose_vulnerable.rs` - Vulnerable Rust implementation
+- `ct_analyzer/tests/test_samples/vulnerable.php` - Vulnerable PHP implementation
+- `ct_analyzer/tests/test_samples/vulnerable.ts` - Vulnerable TypeScript implementation
+- `ct_analyzer/tests/test_samples/vulnerable.py` - Vulnerable Python implementation
+- `ct_analyzer/tests/test_samples/vulnerable.rb` - Vulnerable Ruby implementation
+
+These implement the Decompose and UseHint algorithms from ML-DSA (FIPS-204) as test cases.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+name: Constant-Time Check
+
+on: [push, pull_request]
+
+jobs:
+  ct-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e .
+
+      - name: Check constant-time properties
+        run: |
+          ct-analyzer --github src/crypto/*.c
+```
+
+### GitLab CI
+
+```yaml
+ct-check:
+  stage: test
+  script:
+    - uv pip install -e .
+    - ct-analyzer --json src/crypto/*.c > ct-report.json
+  artifacts:
+    reports:
+      codequality: ct-report.json
+```
+
+## Limitations
+
+1. **Compiler Output Analysis**: Analyzes what the compiler produces, not runtime behavior. Cannot detect:
+   - Cache timing attacks from memory access patterns
+   - Microarchitectural side-channels (Spectre, etc.)
+   - Processor-specific optimizations
+
+2. **No Data Flow Analysis**: Flags all dangerous instructions regardless of whether they operate on secret data. Manual review is needed to determine if flagged code handles secrets. **This means false positives are expected** - for example, division used in loop bounds with public constants will be flagged even though it's not a vulnerability.
+
+3. **False Positive Verification**: For each flagged violation, verify the operands:
+   - If operands are compile-time constants or public parameters → likely false positive
+   - If operands are derived from keys, plaintext, or secrets → true positive
+   - See the SKILL.md documentation for detailed triage guidance
+
+4. **Compiler Variations**: Different compilers/versions may produce different assembly. Test with:
+   - Multiple optimization levels
+   - Multiple compilers
+   - Target production architectures
+
+5. **Scripting Languages**: PHP, JavaScript/TypeScript, Python, and Ruby are supported via bytecode analysis.
+
+## Running Tests
+
+```bash
+python3 ct_analyzer/tests/test_analyzer.py
+```
+
+## References
+
+- [Cryptocoding Guidelines](https://github.com/veorq/cryptocoding)
+- [KyberSlash Attack](https://kyberslash.cr.yp.to/)
+- [NIST FIPS 204: ML-DSA](https://csrc.nist.gov/pubs/fips/204/final)
+- [Trail of Bits ML-DSA Implementation](https://github.com/trailofbits/ml-dsa)
+
+## Acknowledgments
+
+Based on the [test_ct utility](https://github.com/trailofbits/ml-dsa/pull/16) created for ML-DSA.

package/skills/security-constant-time-analysis/commands/ct-check.md

@@ -0,0 +1,20 @@
+---
+name: trailofbits:ct-check
+description: Detects timing side-channels in cryptographic code
+argument-hint: "<source-file> [--warnings] [--json] [--arch <arch>]"
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Check Constant-Time Properties
+
+**Arguments:** $ARGUMENTS
+
+Parse arguments:
+1. **Source file** (required): Path to source file to analyze
+2. **Flags** (optional): `--warnings`, `--json`, `--arch <arch>`, `--opt-level <level>`, `--func <pattern>`
+
+Invoke the `constant-time-analysis` skill with these arguments for the full workflow.