StayAwakeBot

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

• Security sentinel — a supply-chain worm hunter that detects, alerts on, and auto-fixes self-propagating malware, opening remediation PRs and gating CI. It runs locally through the terse saw command, and its exit code is the verdict.
• Health sentinel — a URL/uptime availability monitor (HTTP status, latency, TLS, keyword checks) that reports to the terminal, and to a GitHub issue or Slack when you configure one.

Run either bot as a console script locally, or as a GitHub Actions workflow — the same packaged code in both places. Neither writes reports into your repository.

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"

Scan for supply-chain worms — the security sentinel. Local by default; the exit code is the verdict (0 clean, 1 findings), so a CI gate just reads it:

saw scan                                     # the current repository
saw scan ~/dev                               # every repository under a path
saw scan --config config/security.yml        # with an operator-chosen allowlist

Check uptime — the health sentinel:

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

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 required
      - 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 your-org -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.

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
• Prerequisites — supported Python versions and install troubleshooting
• Security baseline — hardening checklist for any repo
• 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.