crucible-mcp 0.4.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

crucible/enforcement/budget.py

@@ -0,0 +1,179 @@
+"""Token budget estimation and tracking for LLM compliance assertions."""
+
+from crucible.enforcement.models import (
+    Assertion,
+    AssertionType,
+    BudgetState,
+    ComplianceConfig,
+)
+
+# Average tokens per character (rough estimate for code)
+TOKENS_PER_CHAR = 0.25
+
+# Base overhead for each LLM call (system prompt, response format, etc.)
+BASE_OVERHEAD_TOKENS = 200
+
+# Minimum tokens for compliance prompt
+MIN_COMPLIANCE_TOKENS = 50
+
+
+def estimate_assertion_tokens(assertion: Assertion, content_length: int) -> int:
+    """Estimate tokens needed to run an LLM assertion.
+
+    Args:
+        assertion: The assertion to estimate
+        content_length: Length of content to analyze in characters
+
+    Returns:
+        Estimated token count for input
+    """
+    if assertion.type != AssertionType.LLM:
+        return 0
+
+    # Content tokens
+    content_tokens = int(content_length * TOKENS_PER_CHAR)
+
+    # Compliance prompt tokens
+    compliance_tokens = 0
+    if assertion.compliance:
+        compliance_tokens = max(
+            MIN_COMPLIANCE_TOKENS,
+            int(len(assertion.compliance) * TOKENS_PER_CHAR),
+        )
+
+    return BASE_OVERHEAD_TOKENS + content_tokens + compliance_tokens
+
+
+def estimate_total_budget(
+    assertions: list[Assertion],
+    content_length: int,
+) -> int:
+    """Estimate total tokens needed to run all LLM assertions.
+
+    Args:
+        assertions: List of assertions (filters to LLM only)
+        content_length: Length of content to analyze
+
+    Returns:
+        Estimated total token count
+    """
+    total = 0
+    for assertion in assertions:
+        if assertion.type == AssertionType.LLM:
+            total += estimate_assertion_tokens(assertion, content_length)
+    return total
+
+
+def sort_by_priority(assertions: list[Assertion]) -> list[Assertion]:
+    """Sort assertions by priority (critical first).
+
+    Args:
+        assertions: Assertions to sort
+
+    Returns:
+        Sorted list (critical > high > medium > low)
+    """
+    return sorted(assertions, key=lambda a: a.priority.rank)
+
+
+def select_within_budget(
+    assertions: list[Assertion],
+    content_length: int,
+    budget: int,
+) -> tuple[list[Assertion], list[Assertion]]:
+    """Select assertions that fit within token budget.
+
+    Args:
+        assertions: Assertions to select from (should be pre-sorted by priority)
+        content_length: Length of content to analyze
+        budget: Token budget (0 = unlimited)
+
+    Returns:
+        Tuple of (selected_assertions, skipped_assertions)
+    """
+    if budget == 0:
+        # Unlimited budget
+        return list(assertions), []
+
+    selected: list[Assertion] = []
+    skipped: list[Assertion] = []
+    tokens_used = 0
+
+    for assertion in assertions:
+        if assertion.type != AssertionType.LLM:
+            continue
+
+        estimated = estimate_assertion_tokens(assertion, content_length)
+
+        if tokens_used + estimated <= budget:
+            selected.append(assertion)
+            tokens_used += estimated
+        else:
+            skipped.append(assertion)
+
+    return selected, skipped
+
+
+def filter_llm_assertions(assertions: list[Assertion]) -> list[Assertion]:
+    """Filter to only LLM-type assertions.
+
+    Args:
+        assertions: All assertions
+
+    Returns:
+        Only assertions with type=llm
+    """
+    return [a for a in assertions if a.type == AssertionType.LLM]
+
+
+def create_budget_state(config: ComplianceConfig) -> BudgetState:
+    """Create initial budget state from config.
+
+    Args:
+        config: Compliance configuration
+
+    Returns:
+        Fresh BudgetState
+    """
+    return BudgetState(total_budget=config.token_budget)
+
+
+def prepare_llm_assertions(
+    assertions: list[Assertion],
+    content_length: int,
+    config: ComplianceConfig,
+) -> tuple[list[Assertion], BudgetState]:
+    """Prepare LLM assertions for execution.
+
+    Filters to LLM assertions, sorts by priority, and selects within budget.
+
+    Args:
+        assertions: All loaded assertions
+        content_length: Length of content to analyze
+        config: Compliance configuration
+
+    Returns:
+        Tuple of (assertions_to_run, budget_state)
+    """
+    # Filter to LLM assertions only
+    llm_assertions = filter_llm_assertions(assertions)
+
+    if not llm_assertions:
+        return [], create_budget_state(config)
+
+    # Sort by priority
+    sorted_assertions = sort_by_priority(llm_assertions)
+
+    # Select within budget
+    selected, skipped = select_within_budget(
+        sorted_assertions,
+        content_length,
+        config.token_budget,
+    )
+
+    # Create budget state
+    state = create_budget_state(config)
+    for assertion in skipped:
+        state.skip(assertion.id)
+
+    return selected, state

crucible/enforcement/bundled/error-handling.yaml

@@ -0,0 +1,84 @@
+version: "1.0"
+name: error-handling
+description: Error handling best practices to prevent silent failures
+linked_knowledge: ERROR_HANDLING.md
+
+assertions:
+  # High: Silent failures
+  - id: no-bare-except
+    type: pattern
+    pattern: "except\\s*:"
+    message: "Bare except catches everything including SystemExit/KeyboardInterrupt - catch specific exceptions"
+    severity: warning
+    priority: high
+    languages: [python]
+
+  - id: no-pass-in-except
+    type: pattern
+    pattern: "except[^:]*:\\s*\\n\\s*pass\\s*$"
+    message: "Empty except block silently swallows errors - log or re-raise"
+    severity: warning
+    priority: high
+    languages: [python]
+
+  - id: no-empty-catch
+    type: pattern
+    pattern: "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}"
+    message: "Empty catch block silently swallows errors - log or re-throw"
+    severity: warning
+    priority: high
+    languages: [javascript, typescript]
+
+  # Medium: Pokemon exception handling
+  - id: no-catch-exception
+    type: pattern
+    pattern: "except\\s+Exception\\s*:"
+    message: "Catching Exception is too broad - catch specific exception types"
+    severity: info
+    priority: medium
+    languages: [python]
+
+  - id: no-catch-base-exception
+    type: pattern
+    pattern: "except\\s+BaseException\\s*:"
+    message: "Catching BaseException includes SystemExit/KeyboardInterrupt - use Exception or specific types"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  # Medium: Error suppression
+  - id: no-ignore-errors-flag
+    type: pattern
+    pattern: "errors\\s*=\\s*[\"']ignore[\"']"
+    message: "errors='ignore' silently drops data - use 'replace' or handle explicitly"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  # Info: Best practices
+  - id: prefer-contextlib-suppress
+    type: pattern
+    pattern: "except\\s+\\w+\\s*:\\s*\\n\\s*pass\\s*$"
+    message: "Consider contextlib.suppress() for intentionally ignoring specific exceptions"
+    severity: info
+    priority: low
+    languages: [python]
+
+  # LLM assertion for complex error handling patterns
+  - id: error-handling-semantic
+    type: llm
+    compliance: |
+      Check that error handling follows best practices:
+      1. Errors are not silently swallowed (no empty except/catch blocks that do nothing)
+      2. Exceptions are logged or reported before being suppressed
+      3. Error messages provide enough context to debug issues
+      4. Errors at API/system boundaries are handled (not just propagated)
+    message: "Error handling may need improvement"
+    severity: warning
+    priority: medium
+    languages: [python, javascript, typescript]
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"

crucible/enforcement/bundled/security.yaml

@@ -0,0 +1,123 @@
+version: "1.0"
+name: security
+description: Security assertions to catch common vulnerabilities
+linked_knowledge: SECURITY.md
+
+assertions:
+  # Critical: Code execution risks
+  - id: no-eval
+    type: pattern
+    pattern: "\\beval\\s*\\("
+    message: "eval() is dangerous - use ast.literal_eval() for data or safer alternatives"
+    severity: error
+    priority: critical
+    languages: [python, javascript, typescript]
+
+  - id: no-exec
+    type: pattern
+    pattern: "\\bexec\\s*\\("
+    message: "exec() allows arbitrary code execution - avoid or sandbox carefully"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  # Critical: Shell injection
+  - id: no-shell-true
+    type: pattern
+    pattern: "shell\\s*=\\s*True"
+    message: "shell=True enables shell injection - use shell=False with argument list"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  - id: no-os-system
+    type: pattern
+    pattern: "os\\.system\\s*\\("
+    message: "os.system() is vulnerable to shell injection - use subprocess with shell=False"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  # Critical: Deserialization
+  - id: no-pickle-load
+    type: pattern
+    pattern: "pickle\\.load|pickle\\.loads|cPickle\\.load"
+    message: "pickle can execute arbitrary code - use json or msgpack for untrusted data"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  - id: no-yaml-unsafe-load
+    type: pattern
+    pattern: "yaml\\.load\\s*\\([^)]*\\)(?!.*Loader)"
+    message: "yaml.load() without Loader is unsafe - use yaml.safe_load()"
+    severity: error
+    priority: critical
+    languages: [python]
+
+  # High: Hardcoded secrets
+  - id: no-hardcoded-password
+    type: pattern
+    pattern: "(?i)(password|passwd|pwd)\\s*=\\s*[\"'][^\"']{4,}[\"']"
+    message: "Possible hardcoded password - use environment variables or secrets manager"
+    severity: error
+    priority: high
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"
+        - "**/*.md"
+
+  - id: no-hardcoded-api-key
+    type: pattern
+    pattern: "(?i)(api[_-]?key|apikey|secret[_-]?key)\\s*=\\s*[\"'][a-zA-Z0-9]{16,}[\"']"
+    message: "Possible hardcoded API key - use environment variables or secrets manager"
+    severity: error
+    priority: high
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"
+        - "**/*.md"
+
+  # High: SQL injection
+  - id: no-string-sql
+    type: pattern
+    pattern: "execute\\s*\\(\\s*[\"']\\s*SELECT|execute\\s*\\(\\s*f[\"']|execute\\s*\\([^)]*%\\s*\\("
+    message: "Possible SQL injection - use parameterized queries"
+    severity: error
+    priority: high
+    languages: [python]
+
+  # Medium: Weak crypto
+  - id: no-md5-security
+    type: pattern
+    pattern: "hashlib\\.md5|MD5\\s*\\(|md5\\.new"
+    message: "MD5 is cryptographically broken - use SHA-256 or better for security"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  - id: no-sha1-security
+    type: pattern
+    pattern: "hashlib\\.sha1|SHA1\\s*\\(|sha1\\.new"
+    message: "SHA-1 is deprecated for security - use SHA-256 or better"
+    severity: warning
+    priority: medium
+    languages: [python]
+
+  # Medium: Insecure random
+  - id: no-random-for-security
+    type: pattern
+    pattern: "\\brandom\\.(choice|randint|random|uniform)\\s*\\("
+    message: "random module is not cryptographically secure - use secrets module"
+    severity: warning
+    priority: medium
+    languages: [python]
+    applicability:
+      exclude:
+        - "**/test_*.py"
+        - "**/*_test.py"
+        - "**/tests/**"

crucible/enforcement/bundled/smart-contract.yaml

@@ -0,0 +1,110 @@
+version: "1.0"
+name: smart-contract
+description: Smart contract security patterns for Solidity/Vyper
+linked_knowledge: SMART_CONTRACT.md
+
+assertions:
+  # Critical: Reentrancy
+  - id: state-after-external-call
+    type: pattern
+    pattern: "\\.call\\{[^}]*\\}\\([^)]*\\)[^;]*;[^}]*\\b(balances|_balances|userBalances|amounts)\\s*\\["
+    message: "State change after external call - potential reentrancy vulnerability (CEI violation)"
+    severity: error
+    priority: critical
+    languages: [solidity]
+
+  - id: transfer-without-reentrancy-guard
+    type: llm
+    compliance: |
+      Check for reentrancy vulnerabilities:
+      1. External calls (.call, .transfer, .send) should come AFTER state changes (CEI pattern)
+      2. Functions making external calls should have reentrancy guards (nonReentrant modifier)
+      3. State variables should be updated before external calls, not after
+      4. Check-effects-interactions pattern: checks first, then effects (state changes), then interactions (external calls)
+    message: "Potential reentrancy vulnerability - apply CEI pattern and/or nonReentrant modifier"
+    severity: error
+    priority: critical
+    model: opus
+    languages: [solidity]
+
+  # Critical: Access control
+  - id: missing-access-control
+    type: pattern
+    pattern: "function\\s+\\w+\\s*\\([^)]*\\)\\s+(external|public)(?![^{]*onlyOwner|[^{]*onlyRole|[^{]*require\\s*\\(\\s*msg\\.sender)"
+    message: "Public/external function may need access control"
+    severity: warning
+    priority: high
+    languages: [solidity]
+
+  - id: tx-origin-auth
+    type: pattern
+    pattern: "require\\s*\\(\\s*tx\\.origin\\s*==|tx\\.origin\\s*==\\s*msg\\.sender"
+    message: "tx.origin for auth is vulnerable to phishing - use msg.sender"
+    severity: error
+    priority: critical
+    languages: [solidity]
+
+  # High: Integer overflow (pre-0.8.0)
+  - id: unchecked-arithmetic
+    type: pattern
+    pattern: "unchecked\\s*\\{[^}]*[+\\-*/]"
+    message: "Unchecked arithmetic - ensure overflow/underflow is intentional and safe"
+    severity: warning
+    priority: high
+    languages: [solidity]
+
+  # High: Front-running
+  - id: block-timestamp-comparison
+    type: pattern
+    pattern: "block\\.timestamp\\s*[<>=]|[<>=]\\s*block\\.timestamp"
+    message: "block.timestamp can be manipulated by miners (~15 sec) - avoid for critical logic"
+    severity: warning
+    priority: medium
+    languages: [solidity]
+
+  # High: Denial of service
+  - id: unbounded-loop
+    type: pattern
+    pattern: "for\\s*\\([^;]*;[^;]*\\.length\\s*;"
+    message: "Loop bounded by dynamic array length - may cause out-of-gas DoS"
+    severity: warning
+    priority: high
+    languages: [solidity]
+
+  # Medium: Best practices
+  - id: missing-zero-address-check
+    type: pattern
+    pattern: "address\\s+\\w+\\s*=[^;]*;(?![^}]*require\\s*\\([^)]*!=\\s*address\\(0\\))"
+    message: "Consider checking for zero address on address parameters"
+    severity: info
+    priority: medium
+    languages: [solidity]
+
+  - id: hardcoded-gas
+    type: pattern
+    pattern: "\\.call\\{[^}]*gas:\\s*\\d+[^}]*\\}"
+    message: "Hardcoded gas values may break with EVM changes - use gasleft() or remove gas limit"
+    severity: warning
+    priority: medium
+    languages: [solidity]
+
+  # LLM: Complex security patterns
+  - id: smart-contract-security-review
+    type: llm
+    compliance: |
+      Perform a security review of this smart contract code:
+      1. Check for reentrancy vulnerabilities (external calls before state changes)
+      2. Verify access control on privileged functions
+      3. Check for integer overflow/underflow risks
+      4. Look for front-running vulnerabilities
+      5. Check for DoS vectors (unbounded loops, block gas limit issues)
+      6. Verify proper validation of external inputs
+      7. Check for unsafe delegatecall usage
+      8. Look for flash loan attack vectors
+    message: "Smart contract security issue detected"
+    severity: error
+    priority: critical
+    model: opus
+    languages: [solidity, vyper]
+    applicability:
+      glob: "**/*.sol"