English | Español | 中文 | 日本語 | Français

Sanctifier.

Catch the bug before someone else cashes it.

Security copilot for Stellar Soroban smart contracts — static analysis, formal verification with Z3, on-chain runtime guards, and an auditor-friendly dashboard, all driven by a single SARIF-clean engine.

---

Why Sanctifier exists?

Note

When an EVM contract ships a bug, the community has a decade of tools — Slither, Mythril, Foundry, Certora — to catch it. Soroban shipped to mainnet in 2024 with almost none of that scaffolding. Every team writes the same review checklist from scratch. Every audit re-discovers the same five footguns.

Sanctifier is the missing layer. One engine, twelve canonical rules, three deployment surfaces. Built specifically for Soroban's authorization model, storage TTL semantics, SEP-41 token interface, and gas/event quirks. Open source. Auditor-grade. Drop-in for CI.

---

What it catches

Every finding has a stable code — S001..S012 — so you can filter, suppress, and trend it across releases.

Core Security Rules (S001–S012)

Code	What it catches	Why it bites
S001	Missing require_auth on state-changing calls	Anyone can drain your contract
S002	panic! / unwrap / expect in contract paths	Locked state, no recovery
S003	Unchecked arithmetic — overflow, underflow, truncation	Silent loss-of-funds rounding
S004	Ledger entries pushing the size threshold	Refusal at write time, mid-tx
S005	Storage-key collisions between data paths	Cross-feature data corruption
S006	Unsafe patterns — including timestamp-as-randomness	Predictable winners, exploit replay
S007	Your custom YAML rules	Your house style, enforced
S008	Inconsistent or missing event emissions	Wallets and indexers go blind
S009	Unhandled Result return values	Silent failures masquerading as success
S010	Upgrade / admin / governance risk	Single-key takeover paths
S011	Z3-disproved invariants	Mathematical guarantees you don't have
S012	SEP-41 token interface deviations	Wallets reject your token

Vulnerability Database

The community vulnerability database matches known CVE-style patterns (SOL-2024-*) against your AST — so a published exploit anywhere becomes a finding everywhere.

Zero-knowledge contracts — the Z001..Z014 series

If your contract verifies ZK proofs on-chain, Sanctifier checks the ways those integrations keep breaking: nullifiers that are never recorded, public inputs that don't commit to the transaction, verifying keys with no ceremony provenance or trusted straight out of storage.

Important

→ docs/zk-roadmap.md is the scope summary: which Z-rules have detectors today, which are documented but not yet wired, and what is deliberately deferred. Start there before reading the 62 individual issues.

The full catalogue lives in docs/rules/, with the vulnerability classes and secure patterns explained in the ZK Security Guide.

---

Live on Soroban testnet — right now

This isn't a slide deck. Sanctifier's Runtime Guard Wrapper, Reentrancy Guard, and Vulnerable-by-design Contract are deployed and emitting on-chain audit events you can stellar contract invoke against today. See LIVE_TESTNET.md for addresses, verification commands, and event logs.

# Tail real-time guard events on the live deployment
stellar events --network testnet --start-ledger <LATEST> \
  --id $RUNTIME_GUARD_CONTRACT_ID

---

Five ways to use it

Surface	For	Time to first finding
sanctifier CLI	Local dev, scripts, hot paths	30 seconds
GitHub Action	Every PR, every push	One commit
Web Dashboard (Next.js)	Auditors, reviewers, hackathon demos	Drag-and-drop a .rs file
VS Code Extension	Inline diagnostics as you type	One install
On-chain Runtime Guard	Forensic trail after deploy	One contract wrap

Same engine under all of them (it cross-compiles to WASM for the browser path), so findings are bit-for-bit identical wherever you scan.

---

30-second quickstart

Note

No Z3 needed to install. sanctifier-cli depends on sanctifier-core with default features off, so cargo install never compiles Z3 and needs no C toolchain. libz3 is only required when you build the workspace from source or depend on sanctifier-core with its default smt feature — see Install options.

# 1. install (Rust 1.78+)
cargo install sanctifier-cli

# 2. scan
sanctifier analyze ./contracts

# 3. integrate into CI — exit 1 on high/critical findings
sanctifier analyze ./contracts --exit-code --format sarif > sanctifier.sarif

# 4. ship a security badge for your README
sanctifier analyze . --format json > report.json
sanctifier badge --report report.json --svg-output sanctifier.svg

What you'll see

⚠️ Authentication Gaps
   → [S001] src/lib.rs:transfer — missing require_auth
   → [S001] src/lib.rs:mint     — missing require_auth

⚠️ Unchecked Arithmetic
   → [S003] src/lib.rs:transfer:30 — operator `-`
   → [S003] src/lib.rs:transfer:33 — operator `+`

⚠️ SEP-41 Deviation
   → [S012] missing `allowance` function

🛡️ 2 known-vulnerability matches from DB v1.0.0
   ❌ [SOL-2024-002] Missing auth on token transfer (CRITICAL)
   🔴 [SOL-2024-003] Unchecked balance underflow (HIGH)

✨ Scan complete · 4 findings · exit 1

Exit code is 1 when critical/high findings are present — wire it into CI as-is.

---

Wire it into your repo (in one PR)

# .github/workflows/sanctifier.yml
name: Sanctifier
on: [pull_request, push]
permissions: { contents: read, security-events: write }
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: HyperSafeD/Sanctifier@main
        with:
          path: .
          format: sarif
          min-severity: high
          upload-sarif: "true"

SARIF lands in GitHub code-scanning so reviewers see annotations inline on PRs.

Tip

Ensure you have security-events: write permissions enabled in your GitHub Actions settings for SARIF uploads to succeed.

---

Run the dashboard locally

Requires Node.js 20+ and npm 10+ (enforced by frontend/package.json engines).

cd frontend
npm ci          # use `npm install` if you are changing dependencies
npm run dev
# → http://localhost:3000

• /scan — drag in a .rs file, get findings in <2s
• /dashboard — load a JSON report, drill in by severity, see a live call-graph
• /playground — try canned vulnerable contracts (auth-gap, overflow, unsafe-PRNG, …)
• /terminal — sanctifier in a terminal emulator for guided demos

---

Install options

Tip

Quick start: For most users, cargo install sanctifier-cli is all you need.

Installation Methods

Every channel below is published automatically from the release workflow on each tagged version.

Method	Command	Best for
Cargo (recommended)	cargo install sanctifier-cli	Most users; needs Rust 1.78+, no Z3 or C toolchain
npm / npx	npx @hypersafed/sanctifier-cli analyze ./contracts	macOS & Linux with no Rust toolchain; fetches the release binary on first run (Node 18+)
Homebrew	brew install HyperSafeD/sanctifier/sanctifier	macOS and Linuxbrew
Scoop (Windows)	scoop install https://raw.githubusercontent.com/HyperSafeD/Sanctifier/main/scoop/sanctifier.json	Windows, with auto-update on new releases
winget (Windows)	winget install HyperSafeD.Sanctifier	Windows, system package manager
Docker	docker run --rm -v $PWD:/src ghcr.io/hypersafed/sanctifier analyze /src	No local Rust needed
GitHub Codespaces		Cloud IDE, pre-configured
From source	git clone https://github.com/HyperSafeD/Sanctifier && cd Sanctifier && make dev-setup && make release	Latest development version; needs libz3 (see below)

Pre-built Binaries

Direct downloads for your platform (no Rust toolchain required):

Platform	Download	Verification
Linux (x86_64)	Download	SHA256
Linux (musl)	Download	SHA256
macOS (Intel)	Download	SHA256
macOS (Apple Silicon)	Download	SHA256
Windows	Download	SHA256

Verifying binaries: Each release includes SHA256 checksums for integrity verification:

# Linux/macOS
curl -LO https://github.com/HyperSafeD/Sanctifier/releases/latest/download/sanctifier-linux-amd64
curl -LO https://github.com/HyperSafeD/Sanctifier/releases/latest/download/sanctifier-linux-amd64.sha256
sha256sum -c sanctifier-linux-amd64.sha256

# Windows (PowerShell)
(Get-FileHash sanctifier-windows-amd64.exe).Hash -eq (Get-Content sanctifier-windows-amd64.exe.sha256)

System Requirements

To install and run the CLI:

• Rust 1.78+ (only when installing via cargo; the binary, Docker, npx, Homebrew, Scoop and winget channels need no toolchain)
• 2GB RAM
• 500MB disk space

To run the dashboard: Node.js 20+ and npm 10+.

To build the workspace from source (make build / make release / cargo test --workspace), sanctifier-core is compiled with its default smt feature, which links Z3:

Platform	Required Packages
Debian/Ubuntu	sudo apt-get install libz3-dev clang libclang-dev build-essential pkg-config
Fedora/RHEL	sudo dnf install z3-devel clang clang-devel
Arch Linux	sudo pacman -S z3 clang
macOS	brew install z3 llvm
Windows	Install Z3 and Visual Studio Build Tools

make dev-setup installs the Rust toolchain, the wasm32-unknown-unknown target, wasm-pack, soroban-cli and the Node dependencies for you — it does not install libz3, which is platform-specific.

Optional:

• soroban-cli for contract deployment features: cargo install soroban-cli
• wasm-pack for WASM analysis: cargo install wasm-pack

Building without Z3

If you depend on sanctifier-core directly and don't need SMT-backed formal verification (rule S011), turn the default features off and re-enable only what you use:

[dependencies]
sanctifier-core = { version = "0.1", default-features = false, features = ["soroban", "parallel"] }

Feature	Default	What it does
smt	on	Z3-backed formal verification (rule S011). Requires libz3 at compile time; drop it for wasm32 targets.
soroban	on	Pulls in soroban-sdk for the runtime SanctifiedGuard trait.
parallel	on	Rayon-backed batch APIs (e.g. AuthGapRule::check_many) that analyse many sources concurrently. Drop it for wasm32, which has no threads; the batch APIs stay available and run serially.

The shipped sanctifier-cli already builds with default-features = false, features = ["parallel"], which is why installing it never pulls in Z3. All rules except S011 (S001–S010, S012, and the Z series) are fully functional without the smt feature.

Verifying Installation

After installation, verify Sanctifier is working:

# Check version
sanctifier --version

# Run environment diagnostics
sanctifier doctor

# Test with a sample scan
sanctifier analyze --help

Updating Sanctifier

Keep your installation up-to-date:

# Update via cargo
cargo install sanctifier-cli --force

# Or use built-in updater with integrity checks
sanctifier update

Troubleshooting Installation

Warning

Common Issues and Fixes

1. "cargo: command not found"

   • Install Rust via rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   • Restart your terminal or run: source ~/.cargo/env

2. "failed to compile z3-sys" (building from source, or depending on sanctifier-core directly)

   • Install Z3 development libraries (see System Requirements above)
   • Or build sanctifier-core without the smt feature (see Building without Z3)
   • Installing the CLI with cargo install sanctifier-cli never hits this — it does not build Z3

3. "sanctifier: command not found" after installation

   • Ensure ~/.cargo/bin is in your PATH
   • Add to shell profile: echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

4. Windows: "VCRUNTIME140.dll not found"

   • Install Microsoft Visual C++ Redistributable

For more detailed troubleshooting, see docs/getting-started.md#troubleshooting.

---

CLI reference

# Full analysis (most flags shown; all have defaults)
sanctifier analyze  [PATH]
    --format text|json|sarif|ndjson   # output format (default: text)
    --limit BYTES                     # ledger entry size cap (default: 64000)
    --timeout SECS                    # per-file timeout, 0 = none (default: 30)
    --exit-code                       # exit 1 when findings meet threshold
    --min-severity critical|high|medium|low  # threshold for --exit-code (default: high)
    --profile strict|lenient|ci|audit # preset overrides --exit-code/--min-severity
    --webhook-url URL                 # POST results here on completion (repeatable)
    --no-cache                        # skip incremental analysis cache

# Other commands
sanctifier diff       [PATH] --baseline <report.json>   # new/resolved findings vs baseline
sanctifier watch      [PATH]              # re-runs on file change
sanctifier workspace  [PATH]              # cargo-workspace-aware scan
sanctifier callgraph  [PATH] --output callgraph.dot
sanctifier harness    [PATH] --output fuzz-harness --target afl|honggfuzz|both
sanctifier badge      --report report.json --svg-output sanctifier.svg
sanctifier fix        [PATH] --rule S003  # apply patcher fixes
sanctifier verify     [PATH]              # Z3-only invariant pass
sanctifier deploy     [PATH] --network testnet|futurenet|mainnet
sanctifier doctor                         # environment diagnostics
sanctifier init       [PATH]              # scaffold project + .sanctify.toml
sanctifier update                         # self-update with checksum check

Every subcommand accepts --format json for machine consumption. Use --format ndjson with analyze for streaming line-delimited output (one JSON object per finding, final {"event":"done"}).

---

Output is a contract, not a vibe

--format json output validates against schemas/analysis-output.json (JSON Schema draft-07). Every report carries a schema_version that bumps independently of the CLI version, so downstream tooling can pin to a schema without coupling to a release cadence.

{
  "metadata":        { "version": "0.1.0", "format": "sanctifier-ci-v1", "timestamp": "…" },
  "summary":         { "critical": 0, "high": 1, "medium": 2, "low": 0 },
  "error_codes":     ["S001", "S003"],
  "auth_gaps":       [{ "location": "src/lib.rs:42", "message": "missing require_auth" }],
  "arithmetic_issues": [{ "location": "src/lib.rs:30", "operator": "-" }],
  "rule_violations": [{ "rule_name": "require_auth_for_args", "severity": "Error",
                        "location": "src/lib.rs:set_admin", "message": "…" }],
  "vuln_db_matches": [{ "id": "SOL-2024-002", "severity": "CRITICAL", "matched_at": "src/lib.rs:55" }],
  "schema_version":  "1.0.0"
}

SARIF 2.1.0 output is canonical for GitHub code-scanning and any SAST aggregator.

Note

--format sarif produces a SARIF 2.1.0 document compatible with GitHub code-scanning. --format ndjson streams one object per finding so large scans can be processed incrementally.

---

Config — .sanctify.toml

ignore_paths        = ["target", ".git"]
enabled_rules       = ["auth_gaps", "panics", "arithmetic", "ledger_size"]
ledger_limit        = 64000
approaching_threshold = 0.8
strict_mode         = false

[[custom_rules]]
name     = "no_unsafe_block"
pattern  = 'unsafe\s*\{'
severity = "error"

Custom rules support full YAML DSL — see docs/rule-authoring-guide.md.

---

Roadmap

Sanctifier is shipping in waves. What's done, what's next, what's wishlist:

Shipped

• 12 canonical analysis rules (S001–S012) with stable codes
• CLI, GitHub Action, Web Dashboard, VS Code extension, WASM build
• Off-chain anomaly detector for recorded runtime calls with Slack/Discord alerts
• Live testnet runtime-guard contracts emitting on-chain audit events
• SARIF + JSON output, draft-07 schema, badge generator
• Diff mode, watch mode, cargo-workspace scan, patcher

In flight (see the contrib-wave issues)

• Real-LLM provider for /api/ai/explain (currently stubbed)
• Editor-agnostic sanctifier lsp for Neovim / Helix / Zed
• Streaming --ndjson output for incremental piping
• GitHub PR comment formatter with delta vs base
• 20+ new engine rules (allowance race, TTL bumps, cross-contract try_call, taint through destructures, …)
• ZK integration — Z001..Z014 rule catalogue, circom/Noir parsing, shielded-contract fixtures, dashboard ZK panel. Scope and status: docs/zk-roadmap.md

Wishlist

• Hosted REST API, Stellar Laboratory plugin, cargo-sanctify subcommand shim, anomaly-detection rules engine for recorded runtime calls

---

Project layout

Sanctifier/
├── tooling/
│   ├── sanctifier-cli/        # CLI binary (the one you install)
│   ├── sanctifier-detector/   # Off-chain anomaly detection service
│   ├── sanctifier-core/       # Static-analysis engine + Z3 backend
│   └── sanctifier-wasm/       # Browser/Node WASM build of the engine
├── frontend/                  # Next.js dashboard, playground, terminal
├── vscode-extension/          # VS Code diagnostics integration
├── contracts/                 # Soroban contracts (fixtures + live targets)
│   ├── runtime-guard-wrapper/ # ← deployed to testnet
│   ├── reentrancy-guard/      # ← deployed to testnet
│   └── vulnerable-contract/   # ← deployed to testnet (demo target)
├── schemas/
│   └── analysis-output.json   # JSON Schema (draft-07) — validated in CI
├── data/
│   └── vulnerability-db.json  # Community-sourced CVE-style patterns
├── action.yml                 # GitHub composite action
├── benchmarks/                # Performance corpora
├── specs/                     # OpenAPI + RFC drafts
└── docs/                      # Guides, ADRs, threat models, case studies

---

New here? Start with the tutorial

Scan your first Soroban contract in 5 minutes →

The tutorial walks you through installing Sanctifier, writing a minimal contract, running your first scan, fixing every finding, and confirming a clean report — all in a single terminal session.

---

Documentation

If you want to…	Read
Get started (tutorial)	docs/getting-started.md
Browse the API reference	API Documentation
Understand every finding code	docs/error-codes.md
Analyse a ZK contract	docs/zk-roadmap.md (scope) · ZK Security Guide · ZK Integration Guide
Wire the runtime guard into your contract	docs/runtime-guards-integration.md
Set up CI	docs/ci-cd-setup.md
Deploy to testnet	docs/soroban-deployment.md
Write your own rule	docs/rule-authoring-guide.md
See it benchmarked	docs/case-studies/soroban-examples.md
Review the threat model	docs/security-threat-model.md
Check service reliability targets	docs/SLO.md — uptime, latency, and error budgets for the hosted API
Rollback procedures for mainnet	ROLLBACK_PROCEDURE.md
Understand versioning policy	VERSIONING_POLICY.md
Browse design decisions	docs/adr/

---

Contributing

Tip

We're picking up momentum and we want the help. ~100 hand-curated [contrib-wave] issues are live, each one with a problem statement, acceptance criteria, file pointers, and difficulty hint.

There's a good first issue for every skill level — bash, Rust, TypeScript, Next.js, GitHub Actions, doc-writing, contract authoring. Start with CONTRIBUTING.md, then pick an issue and say hi.

---

License

MIT — see LICENSE.

_{Built for the Stellar Soroban ecosystem · Mainnet doesn't forgive · Audit-grade, in CI.}