Metadata-Version: 2.4
Name: stayawakebot
Version: 0.1.3
Summary: Distributable monitoring & security sentinel toolkit — uptime checks plus self-propagating-worm detection, remediation, and prevention.
Project-URL: Homepage, https://github.com/Ndevu12/stayAwakeBot
Project-URL: Repository, https://github.com/Ndevu12/stayAwakeBot
Author: Jean Paul Elisa NIYOKWIZERWA
License-Expression: MIT
License-File: LICENSE
Keywords: github-actions,monitoring,security,sentinel,supply-chain,uptime,worm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: aiohttp
Requires-Dist: pyyaml
Provides-Extra: app
Requires-Dist: pyjwt[crypto]>=2.0; extra == 'app'
Provides-Extra: dev
Description-Content-Type: text/markdown

# 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

![StayAwakeBot architecture](public/stayawakebot_architecture.svg)

## Quick start

> **Prerequisites:** Python 3.11+ — see [docs/PREREQUISITES.md](docs/PREREQUISITES.md).

```bash
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:

```yaml
# .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](prevent/SECURITY_BASELINE.md).

## Run via Docker (no local Python needed)

Prefer not to install a Python toolchain at all? Pull the image and scan a mounted repo:

```bash
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:

```bash
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](docs/USAGE.md) — install, run both bots, secrets, GitHub Actions, deploy your own
- [Configuration & Reports](docs/CONFIGURATION.md) — config file fields and report formats
- [Architecture](docs/ARCHITECTURE.md) — package layout and design principles
- [Security architecture](docs/SECURITY_ARCHITECTURE.md) — detection, remediation, prevention
- [Security baseline](prevent/SECURITY_BASELINE.md) — hardening checklist for any repo
- [Releasing](docs/RELEASING.md) — maintainer runbook: tags, PyPI Trusted Publishing, verification
- [Contributing](CONTRIBUTING.md) — development setup and guidelines

## License

MIT — see [LICENSE](LICENSE).
