StayAwakeBot
Supply-chain worm hunting for developer machines and CI.
A single compromised dependency is how one package becomes an organisation-wide incident. Self-propagating packages spread through installs, builds and merges — arriving with code you asked for, and running before you ever read it.
saw hunts them where they land: repositories, lockfiles, installed packages, and the
machine's start-up surface. It runs offline, out of the box. It removes what it confirms, opens the
fix as a pull request, hardens the host and gates the merge.
| Detect | saw scan — repositories, lockfiles and installed dependency trees; read-only. saw hook — each clone, pull, switch, rebase and push. saw audit — this machine and a repository's branch protection, ending with a rotation-safety verdict. |
| Remediate | saw fix — clears a confirmed infection from your checkout and prepares the cleanup branch; --pr opens it as a pull request. saw fix amend replaces past commits that still carry the payload. saw discard undoes the branch. |
| Prevent | saw harden — protections on this machine, each checked once it is written. saw guard — the CI gate that blocks an infected merge. |
| Advisories | saw db — the offline advisory corpus for CVE and malicious-package matching. |
Quick start
Prerequisites: Python 3.11+ — see Your first scan.
pip install stayawakebot
Or the latest from source:
pip install "stayawakebot @ git+https://github.com/Ndevu12/stayAwakeBot@main"
Then hunt. Each of these stands alone:
Scan every repository under your home folder:
saw scan
Or only the folder you are in:
saw scan .
Or sweep every repository under a path:
saw scan ~/dev
Scan with your own allowlist, rather than the packaged defaults:
saw scan --config config/security.yml
Check the machine itself, not a repository — credential hygiene and start-up entries:
saw audit
New here? saw intro is a 60-second tour, and saw search "…" finds the command you want.
The distribution is published as
stayawakebot; the security CLI is the tersesawcommand (see the CLI reference).
Gate the merge
saw guard writes the CI gate, keeps it pinned, and proves branch protection requires it.
Every repository you own should refuse an infected merge. saw guard writes that GitHub Actions
workflow, keeps it pinned, and proves it is enforced — for one repository or a whole organisation.
Each command below stands alone; reach for the one you need.
Set it up. Writes the gate here, for you to review and commit:
saw guard setup
Or raise it as a pull request:
saw guard setup --pr
Check that a repository is actually guarded — present, SHA-pinned, current, and required:
saw guard check
Check a whole organisation, failing if any repository lacks a required gate:
saw guard check --org your-org -f
saw guard setup surgically pin-bumps a gate that already exists rather than replacing it, and
never clobbers a workflow installed by some other means. saw guard check goes further than "is the
file there" — it verifies branch protection actually requires the check, because a gate that is
not required is decoration.
Both sweep many repositories at once (--remote / --user / --org), like saw scan and
saw fix. See the CLI reference.
The workflow, by hand
A minimal equivalent, if you would rather write it yourself than run saw guard setup. The
installed file is not identical — it also carries a weekly pin-drift job and prefers a
GH_SECURITY_TOKEN secret — so run saw guard setup --dry-run to see exactly what it would write.
Save it as .github/workflows/worm-scan.yml:
name: Worm scan
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
pull-requests: write
security-events: write
jobs:
saw-guard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
fetch-depth: 0
- uses: Ndevu12/SAW_GUARD@93fe465d7b0266c6010778999b73b591ae082f3e
with:
version: '0.13.0'
pr-comment: true
upload-sarif: true
The scan only reads: pull-requests: write lets it say what it found on the pull request
(pr-comment), and security-events: write lets it put the findings in the Security tab
(upload-sarif). saw guard setup puts remediation in a second job, so write access exists only on
a run that already found something; see the CLI reference for the shape it installs. fetch-depth: 0
is required, because the scan reads the full history.
About the pins
Ndevu12/SAW_GUARD ("SAW Guard") is the public Action — a thin wrapper that installs the
published stayawakebot scanner from PyPI.
Pin every action by commit SHA, including this one: a tag can be moved to point at different code
after you have reviewed it, a SHA cannot. Here 93fe465d… is SAW Guard v0.1.4 and 3d3c42e5… is
actions/checkout v7.0.1. In production pin version: as well: it selects the stayawakebot
release from PyPI, 0.12.3 here, and otherwise tracks whatever is latest at run time.
Other inputs: config-file to supply your own allowlist, fail-on to choose the verdict that fails
the build (default infected), and upload-sarif to send findings to code scanning.
See Harden a repository.
Run via Docker
Scan a mounted repository from the published image:
docker run --rm -v "$PWD:/repo:ro" ghcr.io/ndevu12/stayawakebot \
saw scan /repo
To keep the report file too, mount a writable dir and run as your own user so the bind-mount is writable:
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/repo" \
ghcr.io/ndevu12/stayawakebot \
saw scan /repo --reports-dir /repo/reports
Tags: :latest, :X.Y.Z, :X.Y, and :sha-<commit>. The image runs as a non-root user, is
built from the same wheel published to PyPI, and ships SLSA provenance + SBOM attestations.
Also in the package
stayawakebot additionally ships a health sentinel — a URL/uptime availability monitor
(HTTP status, latency, TLS and keyword checks) run with stayawake-health-check. It is
independent of saw and shares only the packaging. See
Configuration.
stayawake-health-check --config config/urls.yml
Documentation
saw-docs.ndevuspace.com — the full documentation, searchable and versioned.
- Documentation index — everything below, in one place
- Your first scan — install, scan, read the verdict, act
- Gate a repository — from unguarded to a required check
- CLI reference — every command and flag, documented once
- Configuration · advisory DB
- Trust model · verdicts · fail closed · safety envelope
- Credential hygiene — what a cached-credential finding means, and how to act on one safely
- Harden a repository — the layered baseline for any repo
- Contributing — development setup and guidelines
- Support — where to ask a question, file a bug, or report a false positive
- Security policy — how to report a security issue privately
- Code of conduct — what taking part here commits you to
Sponsor
saw is open source. To sponsor the work, email saw@ndevuspace.com — the same address handles commercial licensing.
License
stayAwakeBot is dual-licensed:
- AGPL-3.0-or-later — free and open source. You must preserve attribution, and if you modify it and convey it or offer it over a network (e.g. as a hosted service), you must release your corresponding source under the AGPL too.
- Commercial license — a paid, proprietary-use option for closed-source or proprietary-SaaS use without the AGPL's source-disclosure obligations. For terms, contact saw@ndevuspace.com.
1 maintainer
Metadata
1 maintainer
Release files for stayawakebot 0.13.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 | |
|---|---|---|---|---|
| stayawakebot-0.13.0.tar.gz | 1.5 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stayawakebot-0.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.1 MB
Release files / stayawakebot-0.13.0.tar.gz
| Download URL | stayawakebot-0.13.0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a575204d6d9eef1377c42203efe30334b3d46560cf5cb192b7357f5c18a3d90
|
|
BLAKE2b-256 checksum How to use checksums |
1587229f195654819b3d403b60fdd1b4e7c6235d028e7c9727f8ca63707780a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / stayawakebot-0.13.0-py3-none-any.whl
| Download URL | stayawakebot-0.13.0-py3-none-any.whl |
|---|---|
| Size | 1.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5d45fe03922401969fea3567861d31f78d112f0fb9c70f0299ba82011b3daee
|
|
BLAKE2b-256 checksum How to use checksums |
0dba45480ae7716bef4f0e127bde8badd69a8e6c18345f86a03879e4e0182433
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logSecurity for stayawakebot 0.13.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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for stayawakebot-0.13.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logA 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.
