stayawakebot 0.1.8

Distributable monitoring & security sentinel toolkit — uptime checks plus self-propagating-worm detection, remediation, and prevention.

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.

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, run, fix, audit, …)
• 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