stayawakebot 0.1.3

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

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"
stayawake-health-check  --config config/urls.yml                    # uptime check
stayawake-security-scan --config config/security.yml --local-only   # worm scan

The distribution is published as stayawakebot (the name stayawake is taken on PyPI by an unrelated project); the import package and stayawake-* commands are unchanged.

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 \
  stayawake-security-scan --local-only --fail-on-findings

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 \
  stayawake-security-scan --local-only --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

• 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

MIT — see LICENSE.