Semantic Guard Analysis

Semantic Guard Analysis

Detect logic vulnerabilities by finding functions that violate the contract's own internal guard patterns. Unlike pattern-matching tools, this approach uses the contract's consistent behavior as its specification.

When to Use

• Auditing smart contracts where traditional tools find nothing suspicious
• Looking for missing require checks, forgotten modifiers, inconsistent access control
• Analyzing contracts with emergency/admin functions that might bypass safety mechanisms
• Detecting logic bugs that are syntactically correct but semantically dangerous
• When you suspect "forgotten check" vulnerabilities

When NOT to Use

• Pure state-state invariant analysis (use state-invariant-detection)
• Full multi-dimensional audit (use behavioral-state-analysis)
• Code quality or gas optimization reviews

Core Principle: The Consistency Hypothesis

"A smart contract is its own specification."

Instead of checking against external rules, analyze what the contract claims to enforce, then find where it breaks its own rules.

If a critical state variable (like user balances) is protected by a security check (like a pause mechanism) in 90% of functions, the 10% without that check are likely vulnerabilities.

The Three-Phase Detection Architecture

Phase 1: AST Extraction & State Mapping

Parse the Solidity code and build a State Interaction Matrix.

For each state variable, track every function that touches it:

Copy code
State Variable: balance
├─ deposit()        → [WRITE] + Guards: [paused, initialized]
├─ withdraw()       → [WRITE] + Guards: [paused, initialized]
├─ transfer()       → [WRITE] + Guards: [paused]
└─ emergencyWithdraw() → [WRITE] + Guards: [] ⚠️

For each function-variable interaction, record:

Extract guard sources:

• Modifier chains (onlyOwner, nonReentrant, whenNotPaused)
• Explicit require statements
• Conditional branches gating state changes
• External calls affecting state
• Event emissions signaling state changes

Phase 2: Dependency Graph Construction

Build a mathematical model of how variables protect each other.

Guard Relationship: If Variable A is checked before Variable B is modified:

Copy code
A → B (A guards B)

Example:

Copy code
paused ──────┐
             ├──→ balance
initialized ─┘

owner ───→ paused
owner ───→ totalSupply

Frequency Weighting: Each guard relationship gets a confidence score:

Copy code
Confidence(guard → state) = |functions applying guard| / |functions modifying state|

• paused guards balance in 9/10 functions → 90% confidence
• owner guards totalSupply in 3/10 functions → 30% confidence (weak)

Composite Dependencies: Track multi-variable guards:

Copy code
(owner AND timeLock) → criticalFunction
(paused OR emergency) → userAccess

Phase 3: Anomaly Detection (The Solver)

Identify functions that violate established patterns.

Algorithm:

Copy code
For each state variable S that can be modified:
  1. M = all functions that write to S
  2. G = common guards across those functions (above threshold)
  3. V = M \ G (functions that modify without guards)
  4. V is the vulnerability set

Threshold-Based Inference:

Severity Classification:

Context-Aware Filtering:

• Constructor and initialize() functions may legitimately bypass patterns
• view/pure functions cannot modify state — skip
• Proxy pattern delegatecall requires special handling
• Emergency functions may intentionally bypass some guards

Workflow

Copy code
Task Progress:
- [ ] Step 1: Parse contract AST and build State Interaction Matrix
- [ ] Step 2: Identify all state variables and their modifying functions
- [ ] Step 3: Map guards (requires, modifiers) for each function-state pair
- [ ] Step 4: Build dependency graph with frequency weighting
- [ ] Step 5: Run anomaly detection (identify V = M \ G)
- [ ] Step 6: Apply privilege overlay (filter legitimate bypasses)
- [ ] Step 7: Score and report findings

Privilege Overlay System

Not all "bypasses" are vulnerabilities. Apply role-based filtering:

Role Classification:

Filtering Rule:

Copy code
For each function f in vulnerability set V:
  1. Identify function privileges (modifiers, access controls)
  2. Compare with other functions at the SAME privilege level
  3. Flag only if bypass is inconsistent WITHIN privilege tier

Output Format

markdownCopy code
## Guard-State Anomaly Report

### Finding: [Title]

**Function:** `functionName()` at `Contract.sol:L145`
**Severity:** [CRITICAL | HIGH | MEDIUM | LOW]
**Confidence:** [Percentage]

**Issue:** Modifies `[state variable]` without checking `[guard]`

**Pattern Evidence:**
- `function1()` checks `[guard]` before modifying `[state]` ✓
- `function2()` checks `[guard]` before modifying `[state]` ✓
- `functionName()` does NOT check `[guard]` before modifying `[state]` ✗

**Guard Frequency:** X out of Y functions (Z%)

**Security Impact:**
[Explanation of what an attacker can do by exploiting this inconsistency]

**Attack Scenario:**
1. [Step-by-step exploit]

**Recommendation:**
Add `require([guard], "[message]")` before modifying `[state]`,
or document why this function intentionally bypasses the check.

Case Study: The "Forgotten Check"

solidityCopy code
contract Vault {
    mapping(address => uint256) public balance;
    bool public paused;

    function deposit() public payable {
        require(!paused, "Contract paused");       // ✓ checks paused
        balance[msg.sender] += msg.value;
    }

    function withdraw(uint256 amount) public {
        require(!paused, "Contract paused");       // ✓ checks paused
        balance[msg.sender] -= amount;
        payable(msg.sender).transfer(amount);
    }

    function adminWithdraw(address user) public onlyOwner {
        // ✗ Missing paused check!
        uint256 amount = balance[user];
        balance[user] = 0;
        payable(owner).transfer(amount);
    }
}

Detection:

Copy code
M_balance = {deposit, withdraw, adminWithdraw}
G_paused = {deposit, withdraw}
V = {adminWithdraw}

Result: adminWithdraw() modifies balance without checking paused
Confidence: 66.7% (2/3 functions check paused)
Severity: HIGH (financial state + admin bypass of safety mechanism)

For more case studies, see {baseDir}/references/case-studies.md. For the full detection algorithm, see {baseDir}/references/detection-algorithm.md.

Rationalizations to Reject

• "The admin is trusted, so skipping the check is fine" → Compromised admin + missing pause check = unstoppable drain
• "This function is only called internally" → Verify all callers; internal doesn't mean safe
• "The pattern only appears in 2 functions" → Even 2/3 consistency is a signal worth investigating
• "It's an emergency function" → Emergency functions should be MORE carefully guarded, not less
• "Traditional tools said it's fine" → Traditional tools check syntax, not semantic consistency