@elizaos/skills 2.0.0-alpha.3

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

@@ -0,0 +1,179 @@
+# Constant-Time Analysis: Python
+
+Analysis guidance for Python scripts. Uses the `dis` module to analyze CPython bytecode for timing-unsafe operations.
+
+## Prerequisites
+
+- Python 3.10+ (bytecode format varies by version)
+
+## Running the Analyzer
+
+```bash
+# Analyze Python file
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.py
+
+# Include warning-level violations
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings crypto.py
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'encrypt|sign' crypto.py
+
+# JSON output for CI
+uv run {baseDir}/ct_analyzer/analyzer.py --json crypto.py
+```
+
+## Dangerous Operations
+
+### Bytecodes (Errors)
+
+**Python < 3.11:**
+
+| Bytecode | Issue |
+|----------|-------|
+| BINARY_TRUE_DIVIDE | Variable-time execution |
+| BINARY_FLOOR_DIVIDE | Variable-time execution |
+| BINARY_MODULO | Variable-time execution |
+| INPLACE_TRUE_DIVIDE | Variable-time execution |
+| INPLACE_FLOOR_DIVIDE | Variable-time execution |
+| INPLACE_MODULO | Variable-time execution |
+
+**Python 3.11+:**
+
+| BINARY_OP Oparg | Operation | Issue |
+|-----------------|-----------|-------|
+| 11 | `/` | Variable-time execution |
+| 12 | `//` | Variable-time execution |
+| 6 | `%` | Variable-time execution |
+| 24 | `/=` | Variable-time execution |
+| 25 | `//=` | Variable-time execution |
+| 19 | `%=` | Variable-time execution |
+
+### Functions (Errors)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `random.random()` | Predictable | `secrets.token_bytes()` |
+| `random.randint()` | Predictable | `secrets.randbelow()` |
+| `random.randrange()` | Predictable | `secrets.randbelow()` |
+| `random.choice()` | Predictable | `secrets.choice()` |
+| `random.shuffle()` | Predictable | Custom with `secrets` |
+| `random.sample()` | Predictable | Custom with `secrets` |
+| `math.sqrt()` | Variable latency | Avoid in crypto |
+| `math.pow()` | Variable latency | Avoid in crypto |
+| `eval()` | Unpredictable timing | Avoid entirely |
+| `exec()` | Unpredictable timing | Avoid entirely |
+
+### Functions (Warnings)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `str.find()` | Early-terminating | Constant-time search |
+| `str.index()` | Early-terminating | Constant-time search |
+| `str.startswith()` | Early-terminating | `hmac.compare_digest()` |
+| `str.endswith()` | Early-terminating | `hmac.compare_digest()` |
+| `in` (strings) | Early-terminating | Constant-time search |
+| `json.dumps()` | Variable-length output | Fixed-length padding |
+| `json.loads()` | Variable-time | Fixed-length input |
+| `base64.b64encode()` | Variable-length output | Fixed-length padding |
+| `pickle.dumps()` | Variable-length output | Avoid for secrets |
+| `pickle.loads()` | Variable-time, security risk | Avoid for secrets |
+
+## Safe Patterns
+
+### String Comparison
+
+```python
+# VULNERABLE: Early exit on mismatch
+if user_token == stored_token:
+    ...
+
+# SAFE: Constant-time comparison
+import hmac
+if hmac.compare_digest(user_token, stored_token):
+    ...
+
+# SAFE: For bytes
+import secrets
+if secrets.compare_digest(user_bytes, stored_bytes):
+    ...
+```
+
+### Random Number Generation
+
+```python
+# VULNERABLE: Predictable
+import random
+token = random.randint(0, 2**128)
+
+# SAFE: Cryptographically secure
+import secrets
+token = secrets.token_bytes(16)
+token_int = secrets.randbits(128)
+random_index = secrets.randbelow(len(items))
+```
+
+### Division Operations
+
+```python
+# VULNERABLE: Division has variable timing
+quotient = secret // divisor
+
+# SAFE: Barrett reduction for constant divisors
+# Precompute: mu = (1 << (2 * BITS)) // divisor
+def barrett_reduce(value: int, divisor: int, mu: int, bits: int) -> int:
+    q = (value * mu) >> (2 * bits)
+    r = value - q * divisor
+    # Constant-time correction
+    mask = -(r >= divisor)
+    return r - (divisor & mask)
+```
+
+## Python Version Notes
+
+### Python 3.11+ Changes
+
+Python 3.11 introduced the `BINARY_OP` bytecode that replaces individual binary operation bytecodes. The analyzer detects division/modulo by checking the oparg:
+
+```
+BINARY_OP               11 (/)    # True division
+BINARY_OP               12 (//)   # Floor division
+BINARY_OP                6 (%)    # Modulo
+```
+
+### Python 3.10 and Earlier
+
+Uses separate bytecodes:
+```
+BINARY_TRUE_DIVIDE
+BINARY_FLOOR_DIVIDE
+BINARY_MODULO
+```
+
+## Cryptography Library Considerations
+
+When using the `cryptography` library:
+
+```python
+# The cryptography library handles constant-time internally
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+# SAFE: Library handles timing protection
+aesgcm = AESGCM(key)
+ciphertext = aesgcm.encrypt(nonce, plaintext, associated_data)
+```
+
+For custom cryptographic code, ensure you:
+1. Use `hmac.compare_digest()` for comparisons
+2. Use `secrets` module for randomness
+3. Avoid division/modulo on secret-derived values
+4. Use fixed-length data representations
+
+## Limitations
+
+### CPython Bytecode Only
+
+The analyzer targets CPython bytecode. Alternative implementations (PyPy, Jython, etc.) have different bytecode formats and timing characteristics.
+
+### JIT Compilation
+
+PyPy and Numba can JIT-compile Python to native code with potentially different timing behavior. Consider additional analysis for JIT-compiled code paths.

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

@@ -0,0 +1,198 @@
+# Constant-Time Analysis: Ruby
+
+Analysis guidance for Ruby scripts. Uses YARV (Yet Another Ruby VM) instruction sequence dump to analyze bytecode for timing-unsafe operations.
+
+## Prerequisites
+
+- Ruby 2.0+ (uses `ruby --dump=insns`)
+
+## Running the Analyzer
+
+```bash
+# Analyze Ruby file
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.rb
+
+# Include warning-level violations
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings crypto.rb
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'encrypt|sign' crypto.rb
+
+# JSON output for CI
+uv run {baseDir}/ct_analyzer/analyzer.py --json crypto.rb
+```
+
+## Dangerous Operations
+
+### Bytecodes (Errors)
+
+| Bytecode | Issue |
+|----------|-------|
+| opt_div | Variable-time execution based on operand values |
+| opt_mod | Variable-time execution based on operand values |
+
+### Bytecodes (Warnings)
+
+| Bytecode | Issue |
+|----------|-------|
+| opt_eq | May early-terminate on secret data |
+| opt_neq | May early-terminate on secret data |
+| opt_lt, opt_le, opt_gt, opt_ge | Comparison may leak timing |
+| branchif, branchunless | Conditional branch on secrets |
+| opt_aref | Array access may leak timing via cache |
+| opt_aset | Array store may leak timing via cache |
+| opt_lshift, opt_rshift | Bit shift timing may vary |
+
+### Functions (Errors)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `rand()` | Predictable | `SecureRandom.random_bytes()` |
+| `Random.new` | Predictable | `SecureRandom` |
+| `srand()` | Sets predictable seed | `SecureRandom` |
+| `Math.sqrt()` | Variable latency | Avoid in crypto |
+
+### Functions (Warnings)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `include?()` | Early-terminating | Constant-time search |
+| `index()` | Early-terminating | Constant-time search |
+| `start_with?()` | Early-terminating | `Rack::Utils.secure_compare()` |
+| `end_with?()` | Early-terminating | `Rack::Utils.secure_compare()` |
+| `match()` | Variable-time | Avoid on secrets |
+| `=~` | Variable-time regex | Avoid on secrets |
+| `to_json()` | Variable-length output | Fixed-length padding |
+| `Marshal.dump()` | Variable-length output | Avoid for secrets |
+| `Marshal.load()` | Variable-time, security risk | Avoid for secrets |
+
+## Safe Patterns
+
+### String Comparison
+
+```ruby
+# VULNERABLE: Early exit on mismatch
+if user_token == stored_token
+  # ...
+end
+
+# SAFE: Constant-time comparison (Rails/Rack)
+require 'rack/utils'
+if Rack::Utils.secure_compare(user_token, stored_token)
+  # ...
+end
+
+# SAFE: ActiveSupport (Rails)
+require 'active_support/security_utils'
+if ActiveSupport::SecurityUtils.secure_compare(user_token, stored_token)
+  # ...
+end
+
+# SAFE: OpenSSL (stdlib)
+require 'openssl'
+if OpenSSL.secure_compare(user_token, stored_token)
+  # ...
+end
+```
+
+### Random Number Generation
+
+```ruby
+# VULNERABLE: Predictable
+token = rand(2**128)
+random_bytes = Random.new.bytes(16)
+
+# SAFE: Cryptographically secure
+require 'securerandom'
+token = SecureRandom.random_bytes(16)
+token_hex = SecureRandom.hex(16)
+token_base64 = SecureRandom.base64(16)
+random_number = SecureRandom.random_number(2**128)
+```
+
+### Division Operations
+
+```ruby
+# VULNERABLE: Division has variable timing
+quotient = secret / divisor
+
+# SAFE: Barrett reduction for constant divisors
+def barrett_reduce(value, divisor, mu, bits)
+  q = (value * mu) >> (2 * bits)
+  r = value - q * divisor
+  # Constant-time correction using bitwise operations
+  mask = -(r >= divisor ? 1 : 0)
+  r - (divisor & mask)
+end
+```
+
+## Rails/Rack Integration
+
+### Secure Compare
+
+Rails and Rack provide constant-time comparison:
+
+```ruby
+# Rack (standalone)
+Rack::Utils.secure_compare(a, b)
+
+# Rails/ActiveSupport
+ActiveSupport::SecurityUtils.secure_compare(a, b)
+
+# OpenSSL (Ruby 2.5+)
+OpenSSL.secure_compare(a, b)
+```
+
+### CSRF Token Comparison
+
+```ruby
+# Rails automatically uses secure_compare for CSRF tokens
+# For custom token validation:
+class ApplicationController < ActionController::Base
+  def verify_api_token
+    provided = request.headers['X-API-Token']
+    expected = current_user.api_token
+
+    # SAFE: Constant-time comparison
+    unless ActiveSupport::SecurityUtils.secure_compare(provided, expected)
+      head :unauthorized
+    end
+  end
+end
+```
+
+## YARV Bytecode Notes
+
+The analyzer uses `ruby --dump=insns` to get YARV instruction sequences. Example output:
+
+```
+== disasm: #<ISeq:vulnerable_function@test.rb:1 (1,0)-(5,3)>
+local table (size: 2, argc: 2)
+[ 2] value@0    [ 1] modulus@1
+0000 getlocal_WC_0     value@0
+0002 getlocal_WC_0     modulus@1
+0004 opt_div           <calldata!mid:/, argc:1>
+0006 leave
+```
+
+The `opt_div` instruction at offset 0004 is flagged as a timing vulnerability.
+
+## Limitations
+
+### MRI Ruby Only
+
+The analyzer targets MRI (Matz's Ruby Interpreter) YARV bytecode. Alternative implementations (JRuby, TruffleRuby) have different bytecode formats:
+
+- **JRuby**: Compiles to JVM bytecode
+- **TruffleRuby**: Uses GraalVM intermediate representation
+
+### Method Caching
+
+Ruby's method dispatch involves caching that can affect timing. Even with constant-time operations, method lookup timing may leak information about code paths.
+
+### Gem Dependencies
+
+When auditing gems:
+1. Check if the gem uses `SecureRandom` instead of `rand`
+2. Verify string comparisons use `secure_compare`
+3. Look for division/modulo operations on sensitive data

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

@@ -0,0 +1,288 @@
+# Constant-Time Analysis: Swift
+
+Analysis guidance for Swift targeting iOS, macOS, watchOS, and tvOS. Swift compiles to native code, making it subject to the same CPU-level timing side-channels as C, C++, Go, and Rust.
+
+## Understanding Swift Compilation
+
+Swift compiles directly to native machine code:
+
+```text
+Source Code (.swift)
+        |
+        v
+    swiftc (Swift Compiler / LLVM)
+        |
+        v
+   Native Assembly
+        |
+        v
+   Machine Code (binary)
+```
+
+**Key implications:**
+
+1. **Same vulnerabilities as C** - Division, branches, and table lookups have data-dependent timing
+2. **LLVM backend** - Swift uses LLVM, so analysis is similar to clang-compiled code
+3. **Architecture matters** - x86_64 (Mac) and arm64 (iOS devices, Apple Silicon) have different instruction sets
+
+## Running the Analyzer
+
+```bash
+# Analyze Swift for native architecture
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift
+
+# Analyze for iOS device (arm64)
+uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift
+
+# Analyze for Intel Mac
+uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.swift
+
+# Test multiple optimization levels (RECOMMENDED)
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.swift
+uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O2 crypto.swift
+
+# Include conditional branch warnings
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings crypto.swift
+
+# CI-friendly JSON output
+uv run {baseDir}/ct_analyzer/analyzer.py --json crypto.swift
+```
+
+## Dangerous Instructions by Architecture
+
+### ARM64 (iOS devices, Apple Silicon Macs)
+
+| Category | Instructions | Risk |
+|----------|--------------|------|
+| Division | `UDIV`, `SDIV` | Early termination optimization; variable-time |
+| Floating-Point | `FDIV`, `FSQRT` | Variable latency based on operand values |
+| Conditional Branches | `B.EQ`, `B.NE`, `CBZ`, `CBNZ`, etc. | Timing leak if condition depends on secrets |
+
+### x86_64 (Intel Macs)
+
+| Category | Instructions | Risk |
+|----------|--------------|------|
+| Division | `DIV`, `IDIV`, `DIVQ`, `IDIVQ` | Data-dependent timing |
+| Floating-Point | `DIVSS`, `DIVSD`, `SQRTSS`, `SQRTSD` | Variable latency |
+| Conditional Branches | `JE`, `JNE`, `JZ`, `JNZ`, etc. | Timing leak if condition depends on secrets |
+
+## Constant-Time Patterns
+
+### Replace Division
+
+```swift
+// VULNERABLE: Division instruction emitted
+let q = secretValue / divisor
+
+// SAFE: Barrett reduction (for fixed divisor)
+// Precompute: mu = (1 << 32) / divisor
+let mu: UInt64 = (1 << 32) / UInt64(divisor)
+let q = Int32((UInt64(secretValue) &* mu) >> 32)
+```
+
+### Replace Branches
+
+```swift
+// VULNERABLE: Branch timing reveals secret
+let result = secret != 0 ? a : b
+
+// SAFE: Constant-time selection using bitwise ops
+let mask = Int32(bitPattern: UInt32(bitPattern: -Int32(secret != 0 ? 1 : 0)))
+// Better approach with no branch:
+let nonZero = (secret | -secret) >> 31  // -1 if secret != 0, else 0
+let result = (a & nonZero) | (b & ~nonZero)
+```
+
+### Replace Comparisons
+
+```swift
+// VULNERABLE: Standard equality may early-terminate
+if computed == expected { ... }
+
+// SAFE: Constant-time comparison
+import CryptoKit  // Available on iOS 13+, macOS 10.15+
+
+// Use Data's built-in constant-time comparison for crypto
+if computed.withUnsafeBytes({ cPtr in
+    expected.withUnsafeBytes { ePtr in
+        timingSafeCompare(cPtr, ePtr)
+    }
+}) { ... }
+
+// Manual constant-time comparison
+func constantTimeCompare(_ a: [UInt8], _ b: [UInt8]) -> Bool {
+    guard a.count == b.count else { return false }
+    var result: UInt8 = 0
+    for i in 0..<a.count {
+        result |= a[i] ^ b[i]
+    }
+    return result == 0
+}
+```
+
+### Secure Random
+
+```swift
+// VULNERABLE: Don't use for cryptographic purposes
+import Foundation
+let value = Int.random(in: 0..<100)  // Uses arc4random, generally OK but not verified
+
+// SAFE: Use CryptoKit (iOS 13+, macOS 10.15+)
+import CryptoKit
+
+// Generate secure random bytes
+var randomBytes = [UInt8](repeating: 0, count: 32)
+let status = SecRandomCopyBytes(kSecRandomDefault, randomBytes.count, &randomBytes)
+guard status == errSecSuccess else { /* handle error */ }
+
+// Or use SymmetricKey for key generation
+let key = SymmetricKey(size: .bits256)
+```
+
+## Apple Platform Considerations
+
+### Using CryptoKit (Recommended)
+
+CryptoKit provides constant-time implementations for common operations:
+
+```swift
+import CryptoKit
+
+// HMAC (constant-time internally)
+let key = SymmetricKey(size: .bits256)
+let signature = HMAC<SHA256>.authenticationCode(for: data, using: key)
+
+// AES-GCM encryption
+let sealedBox = try AES.GCM.seal(plaintext, using: key)
+
+// Curve25519 key agreement
+let privateKey = Curve25519.KeyAgreement.PrivateKey()
+let sharedSecret = try privateKey.sharedSecretFromKeyAgreement(with: peerPublicKey)
+```
+
+### Security Framework
+
+```swift
+import Security
+
+// Generate cryptographically secure random data
+func secureRandomBytes(count: Int) -> Data? {
+    var bytes = [UInt8](repeating: 0, count: count)
+    let status = SecRandomCopyBytes(kSecRandomDefault, count, &bytes)
+    return status == errSecSuccess ? Data(bytes) : nil
+}
+
+// Keychain for secure storage
+func storeInKeychain(key: Data, account: String) -> Bool {
+    let query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrAccount as String: account,
+        kSecValueData as String: key
+    ]
+    return SecItemAdd(query as CFDictionary, nil) == errSecSuccess
+}
+```
+
+## Swift-Specific Pitfalls
+
+### Optional Unwrapping
+
+```swift
+// Branching on optionals
+if let secret = maybeSecret {  // Introduces branch
+    process(secret)
+}
+
+// Guard statements also branch
+guard let secret = maybeSecret else { return }
+```
+
+### Pattern Matching
+
+```swift
+// Switch/case compiles to branching code
+switch secretEnum {
+case .optionA: handleA()  // Branch
+case .optionB: handleB()  // Branch
+}
+```
+
+### Array Subscripting
+
+```swift
+// Array access indexed by secret leaks via cache timing
+let value = lookupTable[secretIndex]  // Cache timing side-channel
+```
+
+### String Operations
+
+```swift
+// String comparison is NOT constant-time
+if secretString == expectedString { ... }  // Variable-time
+
+// Character iteration may also have timing variations
+for char in secretString { ... }
+```
+
+## Setup Requirements
+
+### Xcode (Recommended)
+
+Install Xcode from the Mac App Store. The Swift compiler is included.
+
+```bash
+# Verify installation
+swiftc --version
+```
+
+### Swift Toolchain (Alternative)
+
+Download from [swift.org](https://swift.org/download/) for standalone installation.
+
+```bash
+# Verify
+swiftc --version
+```
+
+### Cross-Compilation
+
+For analyzing code targeting different architectures:
+
+```bash
+# Analyze for iOS device
+uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift
+
+# Analyze for iOS simulator
+uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.swift
+```
+
+## Common Mistakes
+
+1. **Using Swift's == for byte comparison** - Standard equality comparison may early-terminate; use constant-time comparison
+
+2. **Trusting CryptoKit for all operations** - CryptoKit provides constant-time primitives, but combining them incorrectly can introduce vulnerabilities
+
+3. **String manipulation on secrets** - Swift strings have complex internal representations; timing varies with content
+
+4. **Ignoring optimization levels** - Swift's optimizer can transform safe source code into unsafe assembly; test at multiple -O levels
+
+5. **Platform availability** - CryptoKit requires iOS 13+/macOS 10.15+; older platforms need alternative implementations
+
+## Testing on Different Architectures
+
+Always test your cryptographic code on actual target architectures:
+
+```bash
+# Apple Silicon Mac (arm64)
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift
+
+# Cross-compile for Intel
+uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.swift
+```
+
+## Further Reading
+
+- [Apple CryptoKit Documentation](https://developer.apple.com/documentation/cryptokit)
+- [Apple Security Framework](https://developer.apple.com/documentation/security)
+- [Swift.org Security](https://swift.org/blog/swift-5-release/)
+- [OWASP iOS Security Guide](https://owasp.org/www-project-mobile-security-testing-guide/)