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:

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:

Attribute	Description
Write Access	Does the function modify this variable?
Guard Access	Does the function check this variable in require() or if()?
Read Access	Does the function only read this variable?

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:

A → B (A guards B)

Example:

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

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

Frequency Weighting: Each guard relationship gets a confidence score:

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:

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

Phase 3: Anomaly Detection (The Solver)

Identify functions that violate established patterns.

Algorithm:

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:

Guard Frequency	Classification	Action
≥ 80%	Strong Invariant	Flag violations as HIGH/CRITICAL
50-79%	Weak Invariant	Flag violations as MEDIUM
< 50%	No Pattern	Ignore (too inconsistent)

Severity Classification:

Bypass Type	Severity
Strong invariant on financial state (balance, totalSupply)	Critical
Strong invariant on access control (owner, admin roles)	High
Weak invariant on any state	Medium
Inconsistent pattern with no security implications	Low/Info

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

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:

Role Level	Scrutiny	Rationale
Public functions	Highest	Must follow all established patterns
Owner/Admin functions	Medium	May bypass operational guards, must be consistent with each other
Emergency functions	Lower	Designed for exceptional cases
Internal functions	Context-dependent	Analyze based on callers

Filtering Rule:

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

## 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"

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:

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