📜 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.
🏛️ 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
.solfiles, 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.