Metadata-Version: 2.5
Name: stayawakebot
Version: 0.5.1
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: AGPL-3.0-or-later
License-File: COMMERCIAL-LICENSE.md
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: certifi
Requires-Dist: pyyaml
Provides-Extra: dev
Description-Content-Type: text/markdown

# 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](docs/PREREQUISITES.md).

```bash
pip install stayawakebot                                            # from PyPI (released versions)
```

Or the latest from source:
```bash
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:

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

```bash
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](docs/CLI.md)).

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

**Don't hand-maintain that workflow — let `saw` manage it.** [`saw guard setup`](docs/CLI.md#saw-guard)
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`](docs/CLI.md#saw-guard) 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`:

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

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

```bash
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](docs/CLI.md) — the `saw` security commands (scan, fix, audit, guard, …)
- [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
- [Prerequisites](docs/PREREQUISITES.md) — supported Python versions and install troubleshooting
- [Security baseline](prevent/SECURITY_BASELINE.md) — hardening checklist for any repo
- [Contributing](CONTRIBUTING.md) — development setup and guidelines

## License

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

- **[AGPL-3.0-or-later](LICENSE)** — 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](COMMERCIAL-LICENSE.md)** — 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.

