Metadata-Version: 2.4
Name: seshat-scanner
Version: 1.1.0
Summary: Offline-first, downloadable smart-contract vulnerability scanner + local SQLite archive.
Author: Lord1Egypt
License: MIT License
        
        Copyright (c) 2026 Lord1Egypt (Mohamed Mounir)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Lord1Egypt/Seshat
Project-URL: Repository, https://github.com/Lord1Egypt/Seshat
Keywords: solidity,security,scanner,evm,static-analysis,offline,sqlite
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

<div align="center">

# 📜 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.*

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0-44cc44?style=for-the-badge&labelColor=1a1a2e" alt="v1.0"/>
  <img src="https://img.shields.io/badge/runs-100%25%20local-00d4aa?style=for-the-badge&labelColor=1a1a2e" alt="Local"/>
  <img src="https://img.shields.io/badge/patterns-106-gold?style=for-the-badge&labelColor=1a1a2e" alt="Patterns"/>
  <img src="https://img.shields.io/badge/dependencies-zero-2ea043?style=for-the-badge&labelColor=1a1a2e" alt="Zero deps"/>
  <img src="https://img.shields.io/badge/database-SQLite-003B57?style=for-the-badge&labelColor=1a1a2e&logo=sqlite" alt="SQLite"/>
  <img src="https://img.shields.io/badge/cloud-none-ff4444?style=for-the-badge&labelColor=1a1a2e" alt="No Cloud"/>
  <img src="https://img.shields.io/badge/license-MIT-44cc44?style=for-the-badge&labelColor=1a1a2e" alt="MIT"/>
</p>

<p align="center"><img src="docs/demo.svg" alt="Seshat terminal demo" width="700"/></p>

<p align="center">
  <b>🏛️ Named after Seshat (𓋇)</b> — ancient Egyptian goddess of writing, wisdom, measurement,<br>
  and the divine record-keeper: <i>"Mistress of the House of Books."</i><br>
  <i>Where <a href="https://github.com/Lord1Egypt/MaatEye">MaatEye</a> is the all-seeing eye that judges in the cloud,<br>Seshat is the scribe who records every contract and verdict into an archive that is yours.</i>
</p>

</div>

---

## 🌍 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

```mermaid
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](docs/ARCHITECTURE.md)**, the schema in **[docs/DATABASE_SCHEMA.md](docs/DATABASE_SCHEMA.md)**, and the pattern taxonomy in **[docs/PATTERNS.md](docs/PATTERNS.md)**.

---

## 🚀 Quick start

```bash
# 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](ROADMAP.md)**; per-phase task lists in **[CHECKLIST.md](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](docs/BENCHMARK.md)) · 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](ABOUT.md)**.

---

## 🤝 Contributing & License

This is an early-stage, design-first project by **[Lord1Egypt](https://github.com/Lord1Egypt)**. Issues, pattern ideas, and architecture feedback are welcome while the foundation is being laid. Licensed under **[MIT](LICENSE)** — free for everyone, forever.

<div align="center">
<br>
<i>📜 May every contract be measured, recorded, and remembered. 📜</i>
</div>
