StayAwakeBot

StayAwakeBot is a distributable (pip install-able) Python monitoring and security toolkit. Under one stayawake namespace it ships two bots over a shared core:

• Health sentinel — a URL/uptime availability monitor (HTTP status, latency, TLS, keyword checks) that writes JSON/markdown reports.
• Security sentinel — a supply-chain worm hunter that detects, alerts on, and auto-fixes self-propagating malware (obfuscated loaders, fake fonts, VS Code auto-run tasks, and stealth "evil merges"), opening remediation PRs and gating CI.

Run either bot as a console script locally, or as GitHub Actions workflows that commit reports back to the repository — the same packaged code in both places.

Architecture

Coming soon

Quick start

Prerequisites: Python 3.11+ — see docs/PREREQUISITES.md.

pip install stayawakebot                                            # from PyPI (released versions)

Or the latest from source:

pip install "stayawakebot @ git+https://github.com/Ndevu12/stayAwakeBot@main"

Health check

stayawake-health-check  --config config/urls.yml      

Uptime check (remote-only bot)

saw scan --config config/security.yml --local                       # worm scan (local security CLI)

The distribution is published as stayawakebot. Local security runs through the terse saw command (see the CLI guide).

Gate any repo's CI (GitHub Action)

Add the security sentinel to any repository in one step — no install, no clone:

# .github/workflows/worm-guard.yml
on: [pull_request, push]
jobs:
  worm-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # full history so evil merges are detectable
      - uses: Ndevu12/strix@v1             # pin to a SHA in production
        with:
          fail-on-findings: 'true'

Ndevu12/strix ("StayAwakeBot Strix") is the public Action — a thin wrapper that installs the published stayawakebot scanner from PyPI. Pin @<sha> rather than @v1 for tamper-evident runs. See Security baseline.

Don't hand-maintain that workflow — let saw manage it. saw guard setup writes (or surgically pin-bumps) exactly this gate for you — locally to review + commit, or --pr to open a rolling PR — and saw guard check verifies a repo's gate is present, SHA-pinned, current, and required by branch protection. Both sweep many repos at once (local by default, or --remote/--user/--org), just like saw scan/saw fix:

saw guard check                       # is this repo's gate present + SHA-pinned + current?
saw guard setup --pr                  # install/bump the gate → one rolling PR (never pushes main)
saw guard check --org UB-TechDEV -f   # CI gate: fail if any repo lacks a required gate

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

The exit code is the verdict (0 clean, 1 findings). 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.

Note: that provenance attests saw's own build. When saw scans a target it is purely behavioral — it never treats a scanned package's SLSA / PEP-740 / sigstore attestation as a trust signal (Shai-Hulud 2.0 shipped valid provenance). See SECURITY_ARCHITECTURE.md → Provenance is not trust.

Documentation

• CLI command guide — the saw security commands (scan, fix, audit, guard, …)
• Usage — install, run both bots, secrets, GitHub Actions, deploy your own
• Configuration & Reports — config file fields and report formats
• Architecture — package layout and design principles
• Security architecture — detection, remediation, prevention
• Security baseline — hardening checklist for any repo
• Releasing — maintainer runbook: tags, PyPI Trusted Publishing, verification
• Contributing — development setup and guidelines

License

stayAwakeBot is dual-licensed (from v0.1.9 onward):

• 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. Contact the author for terms.

Releases up to and including v0.1.8 were published under the MIT license and remain MIT for those versions.