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: in your repositories, your lockfiles, your installed
dependency tree, and your machine's start-up surface. It then remediates through a pull request
and gates CI, so an infected change cannot merge.
Offline and accurate with zero flags. A default scan needs no network and no configuration.
A CI gate is one line: run saw scan.
| Detect | saw scan — repositories, lockfiles and installed dependency trees. Read-only, always. |
| Remediate | saw fix — prepares a cleanup branch per infected repo, --pr to publish. saw fix amend replaces past commits that still carry the payload and force-updates those branches. saw discard undoes the branch/PR path. |
| Prevent | saw guard — install and verify the CI gate on any repo. saw hook — scan on clone and pull, before you install or build. |
| Audit | saw audit — host hygiene and branch-protection posture, stating plainly what it did not examine. |
| Harden | saw harden — create host denials; in place only after a read-back. Never a project's tree. |
| Advisories | saw db — an offline corpus for dependency 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 the repository 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).
Don't hand-maintain that workflow
Gate any repository's CI with one command — no install, no clone.
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 instead, which never pushes to main:
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:
# .github/workflows/worm-scan.yml
name: Worm scan
on:
push:
branches: [main]
pull_request:
# The scan only reads. `saw guard setup` writes a second job for remediation,
# so that write access exists only on a run that already found something —
# see the CLI reference for the shape it installs.
permissions:
contents: read
pull-requests: write
security-events: write
jobs:
strix:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0 # full history is required
- uses: Ndevu12/strix@93fe465d7b0266c6010778999b73b591ae082f3e # v0.1.4
with:
version: '0.6.0' # pin the scanner too; blank tracks latest
pr-comment: true # say what was found, on the PR
upload-sarif: true # and in the Security tab
About the pins
Ndevu12/strix ("StayAwakeBot Strix") 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. The trailing comment records which release the SHA
corresponds to, so the pin stays readable. In production pin version: as well — it selects the
stayawakebot release from PyPI 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 (no local Python needed)
Prefer not to install a Python toolchain at all? Pull the image and scan a mounted repo:
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.11.4
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.11.4.tar.gz | 1.2 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stayawakebot-0.11.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.6 MB
Release files / stayawakebot-0.11.4.tar.gz
| Download URL | stayawakebot-0.11.4.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e6e591b130ae8e097e3ea69d9e5c06bcc815784fc402c784283336cf9fad9fac
|
|
BLAKE2b-256 checksum How to use checksums |
4395f84e09784c240d9f97def187deaa269a532e0c5a8de3a1948c4d8c1cee22
|
| 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 Sep 15, 2026.
Transparency logRelease files / stayawakebot-0.11.4-py3-none-any.whl
| Download URL | stayawakebot-0.11.4-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
294034bc014a4b77b0ea211a6c1a7b03bfdf420c6829b32b14f51d614d6e313d
|
|
BLAKE2b-256 checksum How to use checksums |
ea06d88e25bd3cde541a990dd30e921dcd9e56023f23c352b54c9524cdf305e7
|
| 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 Sep 15, 2026.
Transparency logSecurity for stayawakebot 0.11.4
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.11.4.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 Sep 15, 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.
