@elizaos/skills 2.0.0-alpha.3

package/skills/sharp-edges/skills/sharp-edges/references/case-studies.md

@@ -0,0 +1,274 @@
+# Real-World Case Studies
+
+Analysis of sharp edges in widely-used libraries. These aren't implementation bugs—they're design decisions that make secure usage difficult.
+
+## GNU Multiple Precision Arithmetic Library (GMP)
+
+GMP is used extensively for cryptographic implementations (RSA, Paillier, ElGamal, etc.) despite being fundamentally unsuitable for cryptography.
+
+### Sharp Edge: Variable-Time Operations
+
+**The Problem**: GMP operations are not constant-time. Timing varies based on input values.
+
+```c
+// DANGEROUS: Timing leaks secret exponent bits
+mpz_powm(result, base, secret_exponent, modulus);
+
+// Each bit of secret_exponent affects timing differently
+// Attacker can recover secret_exponent via timing analysis
+```
+
+**Why This Matters**:
+- Paillier encryption uses `mpz_powm` with secret keys
+- RSA implementations using GMP leak private key bits
+- Even "blinded" implementations often have residual timing leaks
+
+**Detection Pattern**: Any use of GMP (`mpz_*` functions) with secret values:
+- `mpz_powm`, `mpz_powm_sec` (the "sec" version is still not fully constant-time)
+- `mpz_mul`, `mpz_mod` with secret operands
+- `mpz_cmp` for secret comparison
+
+**Real Vulnerabilities**:
+- CVE-2018-16152: Timing attack on strongSwan IKEv2
+- Numerous academic papers demonstrating key recovery from GMP-based crypto
+
+### Sharp Edge: Memory Not Securely Cleared
+
+```c
+mpz_t secret_key;
+mpz_init(secret_key);
+// ... use secret_key ...
+mpz_clear(secret_key);  // Memory NOT securely wiped
+// Secret data may persist in freed memory
+```
+
+**The Problem**: `mpz_clear` doesn't zero memory before freeing. Secrets persist.
+
+### Sharp Edge: Confusing Import/Export API
+
+```c
+// What does this do?
+mpz_export(buf, &count, order, size, endian, nails, op);
+
+// Parameters:
+// - order: 1 = most significant word first, -1 = least significant
+// - endian: 1 = big, -1 = little, 0 = native
+// - nails: bits to skip at top of each word (?!)
+```
+
+**The Problem**: Seven parameters, three of which control byte ordering in different ways. Easy to get wrong, hard to verify correctness.
+
+### Mitigation
+
+For cryptographic use, prefer:
+- **libsodium** for common operations
+- **OpenSSL BIGNUM** (has constant-time variants)
+- **libgmp with mpz_powm_sec** (partial mitigation, not complete)
+
+---
+
+## OpenSSL
+
+The canonical example of a powerful but footgun-laden cryptographic library.
+
+### Sharp Edge: SSL_CTX_set_verify Callback
+
+```c
+// DANGEROUS: Easy to write callback that always returns 1
+SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_callback);
+
+int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) {
+    // Developer thinks: "I'll add logging here"
+    log_certificate(ctx);
+    return 1;  // OOPS: Always accepts, ignoring preverify_ok!
+}
+```
+
+**The Problem**: The callback's return value determines whether verification succeeds. Developers often:
+- Return 1 (success) unconditionally while "just adding logging"
+- Forget that returning non-zero bypasses all verification
+- Copy-paste examples that return 1 for "debugging"
+
+**Correct Pattern**:
+```c
+int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) {
+    if (!preverify_ok) {
+        // Log failure details
+        log_verification_failure(ctx);
+    }
+    return preverify_ok;  // Preserve original decision
+}
+```
+
+### Sharp Edge: Error Handling via ERR_get_error
+
+```c
+// DANGEROUS: Error easily ignored
+EVP_EncryptFinal_ex(ctx, outbuf, &outlen);
+// Did it succeed? Who knows!
+
+// Correct but verbose:
+if (EVP_EncryptFinal_ex(ctx, outbuf, &outlen) != 1) {
+    unsigned long err = ERR_get_error();
+    char buf[256];
+    ERR_error_string_n(err, buf, sizeof(buf));
+    // Handle error...
+}
+```
+
+**The Problem**:
+- Functions return 1 for success (not 0!)
+- Errors accumulate in a thread-local queue
+- Easy to forget to check, easy to check wrong way
+- Error queue must be cleared or errors persist
+
+### Sharp Edge: RAND_bytes vs RAND_pseudo_bytes
+
+```c
+// These look almost identical:
+RAND_bytes(buf, len);        // Cryptographically secure
+RAND_pseudo_bytes(buf, len); // NOT guaranteed secure!
+
+// Worse: RAND_pseudo_bytes returns 1 even when insecure
+int rc = RAND_pseudo_bytes(buf, len);
+// rc == 1 means "success", not "cryptographically random"
+// rc == 0 means "success but not crypto-strength" (!!)
+// rc == -1 means "not supported"
+```
+
+**The Problem**: Function names differ by one word; return values are confusing; the insecure function is not clearly marked dangerous.
+
+### Sharp Edge: Memory Ownership Confusion
+
+```c
+// Who frees this?
+X509 *cert = SSL_get_peer_certificate(ssl);
+// Answer: YOU do (it's a copy)
+
+// Who frees this?
+X509 *cert = SSL_get0_peer_certificate(ssl);  // OpenSSL 3.0+
+// Answer: NOBODY (it's a reference)
+
+// The difference: "get" vs "get0"
+// This convention is NOT obvious or consistently applied
+```
+
+**The Problem**: Memory ownership indicated by subtle naming conventions that aren't documented together and aren't consistent across the API.
+
+### Sharp Edge: EVP_CIPHER_CTX Reuse
+
+```c
+EVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new();
+EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv);
+EVP_EncryptUpdate(ctx, out, &outlen, in, inlen);
+EVP_EncryptFinal_ex(ctx, out + outlen, &tmplen);
+
+// DANGEROUS: Reusing ctx without reset
+EVP_EncryptInit_ex(ctx, NULL, NULL, NULL, iv2);  // New IV only
+// Some state from previous encryption may persist!
+```
+
+**The Problem**: Context reuse rules are complex and vary by cipher mode.
+
+---
+
+## Python's `pickle`
+
+### Sharp Edge: Arbitrary Code Execution by Design
+
+```python
+import pickle
+
+# DANGEROUS: Deserializes arbitrary Python objects
+data = pickle.loads(untrusted_input)
+
+# Attacker sends:
+# b"cos\nsystem\n(S'rm -rf /'\ntR."
+# Result: Executes shell command
+```
+
+**The Problem**: `pickle` is not a data format—it's a code execution format. There is no safe way to unpickle untrusted data, but:
+- The function looks like a data parser
+- The name suggests food preservation, not danger
+- Many developers don't realize the risk
+
+**Mitigation**: Use `json` for data. If you need pickle, use `hmac` to authenticate before unpickling (but even then, prefer safer formats).
+
+---
+
+## YAML Libraries
+
+### Sharp Edge: Code Execution via Tags
+
+```python
+import yaml
+
+# DANGEROUS: yaml.load() executes arbitrary code
+data = yaml.load(untrusted_input)
+
+# Attacker sends:
+# !!python/object/apply:os.system ['rm -rf /']
+```
+
+**The Problem**: YAML's tag system allows arbitrary object instantiation. The "safe" loader is:
+```python
+data = yaml.safe_load(untrusted_input)  # Safe
+data = yaml.load(untrusted_input, Loader=yaml.SafeLoader)  # Also safe
+```
+
+But the dangerous version is the obvious one (`yaml.load()`).
+
+---
+
+## PHP's `strcmp` for Password Comparison
+
+### Sharp Edge: Type Juggling Bypass
+
+```php
+// DANGEROUS: Type juggling attack
+if (strcmp($_POST['password'], $stored_password) == 0) {
+    authenticate();
+}
+
+// Attacker sends: password[]=anything
+// strcmp(array, string) returns NULL
+// NULL == 0 is TRUE in PHP!
+```
+
+**The Problem**:
+- `strcmp` returns `NULL` on type error, not `-1` or `1`
+- PHP's `==` operator coerces `NULL` to `0`
+- `NULL == 0` evaluates to `TRUE`
+- Authentication bypassed
+
+**Fix**:
+```php
+if (hash_equals($stored_hash, hash('sha256', $_POST['password']))) {
+    // Use hash_equals for timing-safe comparison
+    // AND proper password hashing (not shown)
+}
+```
+
+---
+
+## Analysis Template
+
+When examining a library for sharp edges:
+
+### Input → Expected Output
+
+| Input | Expected | Actual | Vulnerability |
+|-------|----------|--------|---------------|
+| `verify_ssl=false` | Clear warning | Silent acceptance | Config cliff |
+| `password=""` | Rejection | Login success | Empty bypass |
+| `algorithm="none"` | Error | Signature skipped | Downgrade |
+| `timeout=-1` | Error | Infinite timeout | Magic value |
+
+### Library Comparison
+
+| Feature | Dangerous Library | Safer Alternative |
+|---------|------------------|-------------------|
+| Bignum crypto | GMP | libsodium, OpenSSL BIGNUM |
+| TLS | Raw OpenSSL | Higher-level wrappers |
+| Serialization | pickle, YAML | JSON, protobuf |
+| Password compare | strcmp | hash_equals, secrets.compare_digest |

package/skills/sharp-edges/skills/sharp-edges/references/config-patterns.md

@@ -0,0 +1,333 @@
+# Configuration Security Patterns
+
+Dangerous configuration patterns that enable security failures.
+
+## Zero/Empty/Null Semantics
+
+### The Lifetime Zero Problem
+
+```yaml
+# What does 0 mean?
+session_timeout: 0    # Infinite timeout? Immediate expiry? Disabled?
+token_lifetime: 0     # Never expires? Already expired? Use default?
+max_attempts: 0       # No attempts allowed? Unlimited attempts?
+```
+
+**Real-world failures:**
+- OTP libraries where `lifetime=0` means "accept any OTP regardless of age"
+- Rate limiters where `max_attempts=0` disables rate limiting
+- Session managers where `timeout=0` means "session never expires"
+
+**Detection**: Any numeric security parameter that accepts 0.
+
+**Fix**: Explicit constants, validation, or separate enable/disable flag.
+
+```python
+# BAD
+def verify_otp(code: str, lifetime: int = 300):
+    if lifetime <= 0:
+        return True  # What??
+
+# GOOD
+def verify_otp(code: str, lifetime: int = 300):
+    if lifetime <= 0:
+        raise ValueError("lifetime must be positive")
+```
+
+### Empty String Bypass
+
+```python
+# Passwords
+if user_password == stored_hash:  # What if stored_hash is ""?
+
+# API keys
+if api_key == config.api_key:  # What if config is empty?
+    grant_access()
+
+# The empty string equals the empty string
+"" == ""  # True - authentication bypassed
+```
+
+**Detection**: String comparisons for authentication without empty checks.
+
+### Null as "Skip"
+
+```javascript
+// DANGEROUS: null means "skip verification"
+function verifySignature(data, signature, publicKey) {
+    if (!publicKey) return true;  // No key = trust everything?
+    return crypto.verify(data, signature, publicKey);
+}
+
+// DANGEROUS: null means "any value"
+function checkRole(user, requiredRole) {
+    if (!requiredRole) return true;  // No requirement = allow all?
+    return user.roles.includes(requiredRole);
+}
+```
+
+## Boolean Traps
+
+### Security-Disabling Flags
+
+```yaml
+# Every one of these has caused real vulnerabilities
+verify_ssl: false
+validate_certificate: false
+check_signature: false
+require_auth: false
+enable_csrf_protection: false
+sanitize_input: false
+```
+
+**Pattern**: Any boolean that disables a security control.
+
+**The typo problem:**
+```yaml
+verify_ssl: fasle   # Typo - what does the parser do?
+verify_ssl: "false" # String "false" - truthy in many languages!
+verify_ssl: 0       # Integer 0 - falsy, but is it valid?
+```
+
+### Double Negatives
+
+```yaml
+# Confusing
+disable_auth: false      # Auth enabled? Let me re-read...
+skip_validation: false   # Validation runs? Think carefully...
+
+# Clear
+auth_enabled: true
+validate_input: true
+```
+
+## Magic Values
+
+### Sentinel Values in Security Parameters
+
+```yaml
+# What do these mean?
+max_retries: -1      # Infinite? Error? Use default?
+cache_ttl: -1        # Never expire? Disabled?
+timeout_seconds: -1  # Wait forever? Use system default?
+
+# Real vulnerability: connection pool with max_connections: -1
+# meant "unlimited" - enabled DoS via connection exhaustion
+```
+
+### Special String Values
+
+```yaml
+# Dangerous patterns
+allowed_origins: "*"       # CORS wildcard
+allowed_hosts: "any"       # Bypass host validation
+log_level: "none"          # Disable security logging
+password_policy: "disabled" # No password requirements
+```
+
+**Detection**: String configs that accept wildcards or "disable" keywords.
+
+## Combination Hazards
+
+### Conflicting Settings
+
+```yaml
+# Both true - which wins?
+require_authentication: true
+allow_anonymous_access: true
+
+# Both specified - conflict
+session_cookie_secure: true
+force_http: true  # HTTP can't use Secure cookies
+
+# Mutually exclusive
+encryption_key: "..."
+encryption_disabled: true
+```
+
+### Precedence Confusion
+
+```yaml
+# In config file
+verify_ssl: true
+
+# But overrideable by environment?
+VERIFY_SSL=false  # Which wins?
+
+# And command line?
+--no-verify-ssl   # Now there are three sources
+```
+
+**Fix**: Document precedence clearly; warn on conflicts; fail on contradictions.
+
+## Environment Variable Hazards
+
+### Sensitive Values in Environment
+
+```bash
+# Common but problematic
+export DATABASE_PASSWORD="secret"
+export API_KEY="sk_live_xxx"
+
+# Risks:
+# - Visible in process listings (ps aux)
+# - Inherited by child processes
+# - Logged in error dumps
+# - Visible in container inspection
+```
+
+### Override Attacks
+
+```python
+# Application trusts environment
+debug = os.environ.get("DEBUG", "false") == "true"
+
+# Attacker with environment access:
+export DEBUG=true  # Enables verbose logging of secrets
+```
+
+**Detection**: Security settings controllable via environment without validation.
+
+## Path Traversal via Config
+
+### Unrestricted Path Configuration
+
+```yaml
+# User-controlled paths
+log_file: "../../../etc/passwd"
+upload_dir: "/etc/nginx/conf.d/"
+template_dir: "../../../etc/shadow"
+
+# Even "read-only" paths can leak secrets
+config_include: "/etc/shadow"
+certificate_file: "/proc/self/environ"
+```
+
+**Fix**: Validate paths; restrict to allowed directories; resolve and check.
+
+## Unvalidated Constructor Parameters
+
+Configuration/parameter classes that accept security-relevant values without validation create "time bombs" - the insecure value is accepted silently at construction, then explodes later during use.
+
+### Algorithm Selection Without Allowlist
+
+```php
+// DANGEROUS: Accepts any string including weak algorithms
+readonly class ServerConfig {
+    public function __construct(
+        public string $hashAlgo = 'sha256',  // Accepts 'md5', 'crc32', 'adler32'
+        public string $cipher = 'aes-256-gcm', // Accepts 'des', 'rc4'
+    ) {}
+}
+
+// Caller can pass insecure values:
+new ServerConfig(hashAlgo: 'md5');  // Silently accepted!
+```
+
+**Detection**: Constructor parameters named `algo`, `algorithm`, `hash*`, `cipher`, `mode`, `*_type` that accept strings without validation.
+
+**Fix**: Validate against an explicit allowlist at construction:
+
+```php
+public function __construct(public string $hashAlgo = 'sha256') {
+    if (!in_array($hashAlgo, ['sha256', 'sha384', 'sha512'], true)) {
+        throw new InvalidArgumentException("Disallowed hash algorithm: $hashAlgo");
+    }
+}
+```
+
+### Timing Parameters Without Bounds
+
+```php
+// DANGEROUS: No minimum or maximum bounds
+readonly class AuthConfig {
+    public function __construct(
+        public int $otpLifetime = 120,     // Accepts 0 (immediate expiry? infinite?)
+        public int $sessionTimeout = 3600, // Accepts -1 (what does this mean?)
+        public int $maxRetries = 5,        // Accepts 0 (no retries? unlimited?)
+    ) {}
+}
+
+// All of these are silently accepted:
+new AuthConfig(otpLifetime: 0);      // OTP always expired or never expires?
+new AuthConfig(otpLifetime: 999999); // ~11 days - replay attacks!
+new AuthConfig(maxRetries: -1);      // Unlimited retries = brute force
+```
+
+**Detection**: Numeric constructor parameters for `*lifetime`, `*timeout`, `*ttl`, `*duration`, `max_*`, `min_*`, `*_seconds`, `*_attempts` without range validation.
+
+**Fix**: Enforce both minimum AND maximum bounds:
+
+```php
+public function __construct(public int $otpLifetime = 120) {
+    if ($otpLifetime < 2) {
+        throw new InvalidArgumentException("OTP lifetime too short (min: 2 seconds)");
+    }
+    if ($otpLifetime > 300) {
+        throw new InvalidArgumentException("OTP lifetime too long (max: 300 seconds)");
+    }
+}
+```
+
+### Hostname/URL Parameters Without Validation
+
+```php
+// DANGEROUS: No format validation
+readonly class NetworkConfig {
+    public function __construct(
+        public string $hostname = 'localhost',  // Accepts anything
+        public string $callbackUrl = '',        // Accepts malformed URLs
+    ) {}
+}
+
+// Silently accepted:
+new NetworkConfig(hostname: '../../../etc/passwd');
+new NetworkConfig(hostname: 'localhost; rm -rf /');
+new NetworkConfig(callbackUrl: 'javascript:alert(1)');
+```
+
+**Detection**: String constructor parameters named `host`, `hostname`, `domain`, `*_url`, `*_uri`, `endpoint`, `callback*` without validation.
+
+**Fix**: Validate format at construction:
+
+```php
+public function __construct(public string $hostname = 'localhost') {
+    if (!filter_var($hostname, FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)) {
+        throw new InvalidArgumentException("Invalid hostname: $hostname");
+    }
+}
+```
+
+### The "Sensible Default" Trap
+
+Having a secure default does NOT protect you - callers can override it:
+
+```php
+// Default is secure...
+public function __construct(
+    public string $hashAlgo = 'sha256'  // Good default!
+) {}
+
+// ...but callers can still shoot themselves
+$config = new Config(hashAlgo: 'md5');  // Oops
+```
+
+**The rule**: If a parameter affects security, validate it. Defaults only help developers who don't specify a value; validation protects everyone.
+
+## Configuration Validation Checklist
+
+For configuration schemas, verify:
+
+- [ ] **Zero/empty rejected**: Numeric security params require positive values
+- [ ] **No empty passwords/keys**: Empty string authentication forbidden
+- [ ] **No security-disabling booleans**: Or require confirmation/separate config
+- [ ] **No magic values**: -1 and wildcards have defined, safe meanings
+- [ ] **Conflict detection**: Contradictory settings produce errors
+- [ ] **Precedence documented**: Clear order when multiple sources exist
+- [ ] **Path validation**: User-provided paths restricted to safe directories
+- [ ] **Type strictness**: "false" string not silently converted to boolean
+- [ ] **Deprecation warnings**: Insecure legacy options warn loudly
+- [ ] **Algorithm allowlist**: Crypto algorithm params validated against safe options
+- [ ] **Timing bounds**: Lifetime/timeout params have both min AND max limits
+- [ ] **Hostname/URL validation**: Network addresses validated at construction
+- [ ] **Constructor validation**: All security params validated, not just defaulted