Skip to main content

📜 Seshat

The Divine Scribe of Smart Contracts

She who measures, records, and remembers — an offline-first smart-contract vulnerability archive & scanner that builds a local database you own.

v1.0 Local Patterns Zero deps SQLite No Cloud MIT

Seshat terminal demo

🏛️ Named after Seshat (𓋇) — ancient Egyptian goddess of writing, wisdom, measurement,
and the divine record-keeper: "Mistress of the House of Books."
Where MaatEye is the all-seeing eye that judges in the cloud,
Seshat is the scribe who records every contract and verdict into an archive that is yours.


🌍 Vision

Seshat is a smart-contract vulnerability scanner you download and run on your own machine. No GitHub Actions. No cloud. No API gatekeeping. It ingests contracts from anywhere, scans them with 100+ detection patterns, and writes everything — source, scans, findings, history — into a local SQLite database you can query, diff, and export, fully offline.

It is built for people who want to own their data and their analysis: auditors triaging a portfolio, researchers building a corpus, teams gating CI without sending source to a third party, and anyone who believes a security tool should work on a plane with the Wi-Fi off.

🔎 Honest by design. Like its sibling MaatEye, Seshat reports review flags — heuristic pattern matches that point a human to code worth inspecting — not confirmed vulnerabilities. A flag means "look here," not "this is exploitable." That honesty is baked into the schema, the severities, and every report.


✨ What makes Seshat different

📜 Seshat 👁️⚖️ MaatEye 🔬 Typical scanners
Runs locally / offline ✅ download & run ❌ cloud (GitHub Actions) ⚠️ varies
Owns a local database ✅ SQLite, queryable ❌ JSON registry ❌ stateless
Detection patterns ✅ 106 50 30–90
Ingests local projects ✅ foundry/hardhat/.sol ❌ tokens only ✅
Scan history & diffing ✅ compare runs ❌ ⚠️ rare
SARIF / IDE export ✅ SARIF 2.1.0 ❌ ⚠️ some
Zero-/low-dependency ✅ stdlib + sqlite3 ✅ ❌ heavy deps
Sends your source anywhere ❌ never ⚠️ explorer fetch ⚠️ varies

🧩 Core features

  • 🗄️ Local vulnerability database — every contract, its source, every scan, and every finding live in seshat.db. Re-openable, queryable with plain SQL, and 100% offline.
  • 🎯 100+ detection patterns — a SWC/CWE-mapped taxonomy across access control, reentrancy, arithmetic, proxies, oracles, governance, token economics, signatures, and more — each with a confidence score and labeled test fixtures.
  • 📥 Ingest from anywhere — local .sol files, Solidity Standard-JSON, Foundry/Hardhat projects, a list of addresses (fetched once, cached forever), raw bytecode, or import an existing MaatEye registry.
  • 🧪 Honest, deduplicated findings — flatten Standard-JSON (and Etherscan's {{…}}), drop bundled dependencies, strip comments/strings, dedup per (pattern, line), and threshold by confidence — so the numbers mean something.
  • 🔁 Scan diffing — compare two scans of the same corpus: what's new, what's fixed, what regressed.
  • 📤 Export everywhere — JSON, CSV, SARIF (for VS Code / CI annotations), Markdown, and a self-contained offline HTML report you can open in any browser.
  • ⚡ Rust performance core — a parallel Rust engine (rust/) reads the same patterns and produces identical findings ≈5–6× faster on large corpora; the zero-dependency Python engine stays the ergonomic default.

🏗️ Architecture at a glance

flowchart TB
    subgraph IN["📥 Ingestion"]
        A1[Local .sol files]
        A2[Foundry / Hardhat project]
        A3[Address list + explorer fetch]
        A4[Standard-JSON / bytecode]
        A5[MaatEye registry import]
    end

    A1 & A2 & A3 & A4 & A5 --> NORM[🧹 Normalize<br/>flatten JSON · drop deps · strip comments]

    NORM --> DB[(🗄️ seshat.db<br/>SQLite)]

    DB --> ENG[🎯 Pattern Engine<br/>100+ patterns · regex · sig · AST<br/>confidence threshold · dedup]
    ENG --> DB

    DB --> Q[🔍 Query & Diff<br/>SQL · canned queries · scan compare]
    DB --> REP[📤 Reporters<br/>JSON · CSV · SARIF · MD · HTML]

    style DB fill:#0d1225,stroke:#ffd700,color:#ffd700
    style ENG fill:#131a30,stroke:#00d4aa,color:#e0e0e0
    style NORM fill:#131a30,stroke:#4a7fc7,color:#e0e0e0

Detailed design lives in docs/ARCHITECTURE.md, the schema in docs/DATABASE_SCHEMA.md, and the pattern taxonomy in docs/PATTERNS.md.


🚀 Quick start

# Install — pure Python, zero runtime dependencies, patterns bundled in
pipx install seshat-scanner       # or: pip install seshat-scanner
# (or grab a standalone binary from the GitHub Releases — no runtime needed)

# Build a local archive from a project (deps auto-excluded), then scan
seshat init
seshat ingest ./my-foundry-project
seshat scan                       # runs all 106 patterns into seshat.db

# Read the results — fully offline
seshat report                     # pretty terminal triage view
seshat report -o report.html      # self-contained offline HTML
seshat report -o findings.sarif   # SARIF for VS Code / CI annotations

# Ask the archive questions
seshat query --canned by-severity
seshat query "SELECT pattern_id, COUNT(*) n FROM findings GROUP BY 1 ORDER BY n DESC"
seshat search "delegatecall"      # full-text search over stored source

# Re-scan only what changed, then see the delta
seshat scan --incremental
seshat diff 1 2                   # new / fixed / regressed

# Ingest by address (fetched once with --online, then cached forever)
seshat ingest --address 0xA0b8... --chain ethereum --online

Everything above runs with no network (the one exception is an explicit --online address fetch, which then caches). seshat --help lists every command.


🗺️ Roadmap

Seshat ships in eight focused phases. Full detail + acceptance criteria in ROADMAP.md; per-phase task lists in CHECKLIST.md.

Phase Theme Outcome
0 🏛️ Foundation & schema Repo, CI, SQLite schema + migrations
1 📥 Ingestion engine Import & normalize from every source
2 🎯 Pattern engine (100+) Matchers, pattern SDK, labeled fixtures
3 🗄️ Local DB & query Persist, SQL/canned queries, scan diff
4 📤 Reporting & UX JSON/CSV/SARIF/MD/HTML, pretty CLI/TUI
5 ⚡ Rust performance core Parallel engine for large corpora
6 📦 Distribution PyPI · binaries · demo
7 🧠 Ecosystem Plugins · IDE/SARIF · interop

Current status: 🎉 v1.0 — all 8 phases shipped (0–7): schema · ingestion · 106-pattern engine · query/diff/incremental · reporting · ⚡ Rust core (≈5–6× faster, identical findings — benchmark) · distribution · plugins/interop.


📜 Philosophy

Seshat recorded the deeds; Ma'at weighed them against the feather.

Truth over flattery. A flag is an invitation to look, not a verdict. The archive is yours, it works offline, and it tells you exactly how confident it is. Read more in ABOUT.md.


🤝 Contributing & License

This is an early-stage, design-first project by Lord1Egypt. Issues, pattern ideas, and architecture feedback are welcome while the foundation is being laid. Licensed under MIT — free for everyone, forever.


📜 May every contract be measured, recorded, and remembered. 📜

Metadata

Release files for seshat-scanner 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for seshat-scanner 1.1.0
File Size Uploaded Provenance Actions
seshat_scanner-1.1.0.tar.gz 85.3 kB Without provenance Details for seshat_scanner-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for seshat-scanner 1.1.0
File Interpreter ABI Platform Actions
seshat_scanner-1.1.0-py3-none-any.whl Python 3 none any Details for seshat_scanner-1.1.0-py3-none-any.whl

Total release size: 194.0 kB

Release files / seshat_scanner-1.1.0.tar.gz

Download URL seshat_scanner-1.1.0.tar.gz
Size 85.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c936a49a2a914a7a9b8d206d7a6d5d2236528348a1e0cde2ec4c28436dabed97
BLAKE2b-256 checksum
How to use checksums
83b780dbba2d8115912369165f7a36dfec402e532927c3b98fee81c32f62dcbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.13

Release files / seshat_scanner-1.1.0-py3-none-any.whl

Download URL seshat_scanner-1.1.0-py3-none-any.whl
Size 108.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
768d5722f0c1d52879494f47aff192d47a9826e1301466d5032a9ea29f196f94
BLAKE2b-256 checksum
How to use checksums
8cd1d3bd6d8c240cd598a3b68390250a32e622321f578064bfd6a6c3547a00ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.13

Security for seshat-scanner 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page