ton-vulnerability-scanner

# TON Vulnerability Scanner

## 1. Purpose

Systematically scan TON blockchain smart contracts written in FunC for platform-specific security vulnerabilities related to boolean logic, Jetton token handling, and gas management. This skill encodes 3 critical vulnerability patterns unique to TON's architecture.

## 2. When to Use This Skill

- Auditing TON smart contracts (FunC language)
- Reviewing Jetton token implementations
- Validating token transfer notification handlers
- Pre-launch security assessment of TON dApps
- Reviewing gas forwarding logic
- Assessing boolean condition handling

## 3. Platform Detection

### File Extensions & Indicators
- **FunC files**: `.fc`, `.func`

### Language/Framework Markers
```func
;; FunC contract indicators
#include "imports/stdlib.fc";

() recv_internal(int my_balance, int msg_value, cell in_msg_full, slice in_msg_body) impure {
    ;; Contract logic
}

() recv_external(slice in_msg) impure {
    ;; External message handler
}

;; Common patterns
send_raw_message()
load_uint(), load_msg_addr(), load_coins()
begin_cell(), end_cell(), store_*()
transfer_notification operation
op::transfer, op::transfer_notification
.store_uint().store_slice().store_coins()
```

### Project Structure
- `contracts/*.fc` - FunC contract source
- `wrappers/*.ts` - TypeScript wrappers
- `tests/*.spec.ts` - Contract tests
- `ton.config.ts` or `wasm.config.ts` - TON project config

### Tool Support
- **TON Blueprint**: Development framework for TON
- **toncli**: CLI tool for TON contracts
- **ton-compiler**: FunC compiler
- Manual review primarily (limited automated tools)

---

## 4. How This Skill Works

When invoked, I will:

1. **Search your codebase** for FunC/Tact contracts
2. **Analyze each contract** for the 3 vulnerability patterns
3. **Report findings** with file references and severity, above them a coverage table carrying a verdict for every pattern
4. **Provide fixes** for each identified issue
5. **Emit the coverage table** — all 3 patterns, each with a verdict

---

## 5. Example Output

When vulnerabilities are found, you'll get a report like this:

```
=== TON VULNERABILITY SCAN RESULTS ===

Project: my-ton-contract
Files Scanned: 3 (.fc, .tact)
Vulnerabilities Found: 2

Coverage: 3/3 patterns reported
 1 Integer as Boolean .............. found   contracts/wallet.fc:45
 2 Fake Jetton Contract ............ found   contracts/staking.fc:85
 3 Forward TON Without Gas Check ... clear   forward amounts fixed at 0.05 TON

---

[CRITICAL] Fake Jetton Contract - Missing Sender Validation
File: contracts/staking.fc:85
Pattern: transfer_notification sender not checked against the stored Jetton wallet
```

---

## 6. Vulnerability Patterns (3 Patterns)

I check for 3 critical vulnerability patterns unique to TON. For detailed detection patterns, code examples, mitigations, and testing strategies, see [VULNERABILITY_PATTERNS.md](resources/VULNERABILITY_PATTERNS.md).

### Pattern Summary:

1. **Integer as Boolean** ⚠️ HIGH - Positive integers used as true; FunC's true is -1
2. **Fake Jetton Contract** ⚠️ CRITICAL - `transfer_notification` sender not validated
3. **Forward TON Without Gas Check** ⚠️ HIGH - Forwarding without reserving gas for the rest of execution

For complete vulnerability patterns with code examples, see [VULNERABILITY_PATTERNS.md](resources/VULNERABILITY_PATTERNS.md).

## 7. Scanning Workflow

### Step 1: Platform Identification
1. Verify FunC language (`.fc` or `.func` files)
2. Check for TON Blueprint or toncli project structure
3. Locate contract source files
4. Identify Jetton-related contracts

### Step 2: Boolean Logic Review
```bash
# Find boolean-like variables
rg "int.*is_|int.*has_|int.*flag|int.*enabled" contracts/

# Check for positive integers used as booleans
rg "= 1;|return 1;" contracts/ | grep -E "is_|has_|flag|enabled|valid"

# Look for NOT operations on boolean-like values
rg "~.*\(|~ " contracts/
```

For each boolean:
- [ ] Uses -1 for true, 0 for false
- [ ] NOT using 1 or other positive integers
- [ ] Logic operations work correctly

### Step 3: Jetton Handler Analysis
```bash
# Find transfer_notification handlers
rg "transfer_notification|op::transfer_notification" contracts/
```

For each Jetton handler:
- [ ] Validates sender address
- [ ] Sender checked against stored Jetton wallet address
- [ ] Cannot trust forward_payload without sender validation
- [ ] Has admin function to set Jetton wallet address

### Step 4: Gas/Forward Amount Review
```bash
# Find forward amount usage
rg "forward_ton_amount|forward_amount" contracts/
rg "load_coins\(\)" contracts/

# Find send_raw_message calls
rg "send_raw_message" contracts/
```

For each outgoing message:
- [ ] Forward amounts are fixed/bounded
- [ ] OR user-provided amounts validated against msg_value
- [ ] Cannot drain contract balance
- [ ] Appropriate send_raw_message flags used

### Step 5: Manual Review
TON contracts require thorough manual review:
- Boolean logic with `~`, `&`, `|` operators
- Message parsing and validation
- Gas economics and fee calculations
- Storage operations and data serialization

---

## 8. Reporting Format

### Coverage Table

Report on every pattern in §6, whether or not it turned anything up. Emit this table above the findings, with
all 3 rows present:

| # | Pattern | Verdict | Evidence |
|---|---------|---------|----------|
| 1 | Integer as Boolean | `clear` | searched `is_`/`has_`/`flag`; all set to -1 |
| 2 | Fake Jetton Contract | | |
| 3 | Forward TON Without Gas Check | | |

Each verdict is one of:

- **`found`** — cite `file:line` and write the finding up in full below.
- **`clear`** — the pattern applies to this contract and the contract handles it. Name the function, stored
  address, or check you searched for, so a reader can repeat the search.
- **`n/a`** — the pattern cannot apply here. Give the reason in one clause ("this contract handles no Jetton
  transfer notifications"). Not having looked is not `n/a`.

Three patterns is a sh