Spectrmachina/Ztrust

Zero-trust software supply-chain security — with shielded Zcash bounties for the people who defend open source

Quick start · How it works · Bounties · Rules · API

Modern software is mostly other people's code. A single poisoned package, a mutable GitHub Action tag or a leaked publish token is enough to compromise thousands of downstream projects — xz-utils, tj-actions/changed-files, event-stream and a steady stream of npm/PyPI malware have all shown it.

ZTrust does two things:

Zero trust applies to code and to money: every dependency is suspect until verified, and every payment is verifiable without exposing the people behind it.

flowchart LR
    subgraph Detect["🛡️ Detect"]
        direction TB
        A["📦 Manifests & lockfiles"] --> SCAN
        B["⚙️ GitHub workflows"] --> SCAN
        C["📝 Source & Dockerfiles"] --> SCAN
        SCAN{{"ztrust scan"}} --> OSV[("OSV.dev")]
        SCAN --> OUT["Console · JSON · SARIF"]
        OUT --> GH["GitHub Security tab"]
    end

    subgraph Reward["💰 Reward"]
        direction TB
        R(["🕵️ Researcher"]) -- "1 · commit hash" --> API["ZTrust Bounty API"]
        R -- "2 · reveal report" --> API
        M(["🧑‍💻 Maintainer"]) -- "3 · triage" --> API
        API -- "4 · z_sendmany" --> Z[("🔒 Zcash shielded pool")]
        Z -- "private payout + memo" --> R
    end

    GH -. "what scanners can't see" .-> R

More diagrams: architecture · bounty protocol · Zcash integration

Ecosystems: requirements*.txt · poetry.lock · uv.lock · package-lock.json (v1–v3) · package.json · go.mod · Cargo.lock

Outputs: rich terminal report · JSON · SARIF 2.1.0 (GitHub code scanning, with security-severity)

Zcash toolkit (pure Python): Bech32/Bech32m & Base58Check address validation, Unified Addresses (ZIP-316), payment URIs (ZIP-321), z_sendmany payouts via zcashd-compatible JSON-RPC / Zallet.

git clone https://github.com/Lostreaksmb/ztrust.git
cd ztrust
pip install -e .

ztrust scan examples/vulnerable-app      # an intentionally broken demo project
ztrust scan .                            # your project

╭───────────────────────────────────────────────────────────────────────────╮
│ ZTrust v0.1.0  /home/me/ztrust/examples/vulnerable-app                    │
│ 7 dependencies · scanners: secrets, typosquat, integrity, ci, vulns · 1.84s│
│  CRITICAL 1   HIGH 9   MEDIUM 6   LOW 3   INFO 1                          │
╰───────────────────────────────────────────────────────────────────────────╯
 Severity  Rule         Finding                                              Location
 CRITICAL  ZT-CI-002    Pwn request: job `preview` checks out untrusted PR…  .github/workflows/pr.yml:10
 HIGH      ZT-TYPO-001  Possible typosquat: `crossenv` imitates `cross-env`  package.json
 HIGH      ZT-INT-007   Dangerous `postinstall` lifecycle script             package.json
 HIGH      ZT-SEC-001   AWS access key ID detected                           app/config.py:2
 HIGH      ZT-VULN-001  GHSA-…: Prototype Pollution in lodash                package.json
 …

Exit codes: 0 clean · 1 findings ≥ --fail-on (default high) · 2 usage error.

# .github/workflows/ztrust.yml
name: ZTrust
on: [push, pull_request]

permissions:
  contents: read
  security-events: write   # upload SARIF to the Security tab

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Lostreaksmb/ztrust@v0.1.0
        with:
          fail-on: high

Findings appear under Security → Code scanning with file/line annotations on pull requests. The action passes its inputs through environment variables — it does not commit the script-injection mistake it detects (ZT-CI-003).

💡 Pin the action to a commit SHA in production — ZTrust will remind you (ZT-CI-001).

Static analysis catches known bad things. The xz-utils backdoor was found by a person who noticed SSH logins were 500 ms slower. Today that kind of work is mostly unpaid. ZTrust creates an economic incentive for it, built on three requirements that ordinary payment rails can't meet:

sequenceDiagram
    autonumber
    actor Mt as Maintainer
    participant API as ZTrust API
    participant W as Zcash wallet
    actor Rs as Researcher
    Mt->>API: create program (payout table, budget, funding UA)
    API-->>Mt: ZIP-321 funding link
    Mt->>W: fund the pool
    Rs->>API: commitment = SHA-256(salt:report) + payout UA
    Rs->>API: reveal(report, salt)
    API->>API: verify hash · earliest commitment wins
    Mt->>API: accept as "critical"
    Mt->>API: payout
    API->>W: z_sendmany (FullPrivacy, encrypted memo)
    W-->>Rs: 🔒 5 ZEC, shielded

stateDiagram-v2
    direction LR
    [*] --> committed
    committed --> revealed: hash ✔
    revealed --> accepted
    revealed --> rejected
    revealed --> duplicate: earlier commit exists
    accepted --> paid: shielded tx
    paid --> [*]

pip install -e ".[server]"
export ZTRUST_ADMIN_TOKEN=dev ZTRUST_ZCASH_NETWORK=test   # mock payouts by default
ztrust serve                                             # → http://127.0.0.1:8080/docs

# in another terminal
FUNDING_UA=utest1... PAYOUT_UA=utest1... ./examples/bounty-flow.sh

Or with Docker:

cp .env.example .env    # set ZTRUST_ADMIN_TOKEN
docker compose up --build

Switch to real payments with ZTRUST_ZCASH_BACKEND=rpc and a Zallet wallet on a Zebra node — see docs/zcash-integration.md.

Drop a .ztrust.yml in the repository root:

exclude:
  - "vendor/**"
  - "tests/fixtures/**"

fail_on: high

disable_rules:
  - "ZT-INT-005"          # we don't use --require-hashes
  - "ZT-SEC-0*"           # globs work too

severity_overrides:
  ZT-CI-001: low

allowlist_packages:       # intentional look-alike names
  - colour

secrets_allowlist:        # regexes for known test values
  - "AKIAIOSFODNN7EXAMPLE"

Silence a single line with a # ztrust:ignore comment.

ztrust/
├── action.yml                    # GitHub Action (composite)
├── Dockerfile · docker-compose.yml
├── src/ztrust/
│   ├── cli.py                    # ztrust scan | deps | commit | pay-uri | check-address | serve
│   ├── engine.py                 # orchestration + policy
│   ├── manifests.py              # 7 manifest / lockfile parsers
│   ├── report.py                 # console · JSON · SARIF
│   ├── scanners/                 # secrets · typosquat · integrity · cicd · vulns
│   ├── bounty/
│   │   ├── zcash.py              # Bech32m, Base58Check, ZIP-321, amounts
│   │   ├── protocol.py           # commit-reveal
│   │   ├── backends.py           # mock + JSON-RPC (zcashd / Zallet)
│   │   └── store.py              # SQLite
│   └── server/app.py             # FastAPI bounty API
├── tests/                        # pytest suite
├── examples/                     # vulnerable demo app + bounty walkthrough
└── docs/                         # architecture, protocol, Zcash, threat model, rules, API, roadmap

• Five scanners, SARIF, GitHub Action
• Bounty API with commit-reveal and shielded payouts
• yarn / pnpm lockfiles, Maven, NuGet, RubyGems
• Sigstore / npm provenance & SLSA verification
• Release-tarball vs source diffing (xz-style backdoors)
• FROST multisig bounty pools, public multi-tenant hub

Full plan: docs/roadmap.md

PRs welcome — start with CONTRIBUTING.md. New detection rules are the most valuable contribution. Found a vulnerability in ZTrust itself? Please follow SECURITY.md.

MIT © 2026 ZTrust contributors