behavioral-state-analysis

QuillShield Security Skills

AI agent skills for advanced smart contract security auditing. These skills teach AI agents (Claude, Cursor) the QuillShield methodology for detecting vulnerabilities that traditional static analysis tools miss.

Quick start

• Claude: Install this repo as a Claude plugin; the marketplace is defined in .claude-plugin/marketplace.json. Enable the plugins you need for your audit.
• Cursor: Reference a skill when auditing — e.g. @plugins/reentrancy-pattern-analysis/skills/reentrancy-pattern-analysis/SKILL.md — or copy plugin skills/ folders into your Cursor skills directory.
• Use the right skill: See the table below and the Skills Overview for when to use each plugin.

Skills Overview

1. Behavioral State Analysis (BSA)

Plugin: plugins/behavioral-state-analysis/

The comprehensive audit methodology. Combines behavioral intent extraction, multi-dimensional threat modeling (economic, access control, state integrity), adversarial simulation with PoC generation, and Bayesian confidence scoring.

Use when: Starting a full smart contract security audit, threat modeling DeFi protocols, or generating exploit proof-of-concepts.

2. Semantic Guard Analysis

Plugin: plugins/semantic-guard-analysis/

Detects logic vulnerabilities by finding functions that bypass security checks (require statements, modifiers) that the contract's own code consistently applies elsewhere. Based on the Consistency Principle: "A smart contract is its own specification."

Use when: Looking for missing access controls, forgotten pause checks, inconsistent modifiers, or logic bugs invisible to pattern-matching tools.

3. State Invariant Detection

Plugin: plugins/state-invariant-detection/

Automatically infers mathematical relationships between state variables (sum, conservation, ratio, monotonic, synchronization) then finds functions that violate them. Catches the vulnerabilities behind the biggest DeFi hacks.

Use when: Auditing for supply/balance mismatches, broken tokenomics, accounting desynchronization, or conservation law violations.

4. Reentrancy Pattern Analysis

Plugin: plugins/reentrancy-pattern-analysis/

Systematically detects all reentrancy variants — classic, cross-function, cross-contract, read-only, and ERC-777/ERC-1155 callback reentrancy. Builds call graphs, verifies CEI pattern compliance, and traces state changes relative to external call positions.

Use when: Auditing contracts with external calls, ETH transfers, token interactions, or multi-contract architectures. Covers the most infamous smart contract vulnerability class.

5. Oracle & Flash Loan Analysis

Plugin: plugins/oracle-flashloan-analysis/

Detects price oracle manipulation and flash loan attack vectors — the most common DeFi attack combination. Classifies oracle trust models (Chainlink, TWAP, spot price), identifies stale prices, circular dependencies, and flash loan atomicity exploitation.

Use when: Auditing DeFi protocols that depend on price data, oracle integrations, lending protocols, or any contract accessible via flash loans.

6. Proxy & Upgrade Safety

Plugin: plugins/proxy-upgrade-safety/

Detects vulnerabilities in upgradeable proxy architectures — storage layout collisions, uninitialized implementations, function selector clashing, and upgrade path safety. Covers Transparent, UUPS, Beacon, Diamond (EIP-2535), and Minimal proxy patterns.

Use when: Auditing upgradeable contracts, reviewing implementation upgrades, or analyzing delegatecall architectures. Critical for the 54.2% of Ethereum contracts that use proxy patterns.

7. Input & Arithmetic Safety

Plugin: plugins/input-arithmetic-safety/

Detects input validation failures (#1 direct exploitation cause at 34.6%) and arithmetic vulnerabilities — precision loss, rounding exploitation, ERC4626 inflation attacks, unsafe casting, and Solidity 0.8+ unchecked block risks.

Use when: Auditing fee calculations, share pricing, exchange rates, unchecked blocks, or any public functions with user-supplied parameters.

8. External Call Safety

Plugin: plugins/external-call-safety/

Detects unsafe external call patterns and token integration vulnerabilities. Covers unchecked return values, fee-on-transfer tokens, rebasing tokens, missing ERC20 return values (USDT), callback risks, unsafe approve patterns, and push vs pull payment analysis.

Use when: Auditing contracts that interact with external contracts, integrate arbitrary ERC20 tokens, or distribute payments.

9. Signature & Replay Analysis

Plugin: plugins/signature-replay-analysis/