GitHub-native dependency intelligence and autonomous remediation.
HawkOps reviews dependency risk, coordinates safe updates, repairs failed migrations, and keeps every decision inside GitHub.
Quick start • Commands • Zero-cost CI • Setup • Operations • Security • Changelog
Dependency maintenance is rarely just a version bump. An update can change an API, break a build, introduce a licence conflict, expose a vulnerable path, or require coordinated changes across several repositories.
HawkOps turns that work into one reviewable GitHub workflow:
| Intelligence | Automation | Governance |
|---|---|---|
| Vulnerability, exploit, licence, reachability, reputation, and compatibility evidence | Update PRs, bounded repair loops, migration recipes, test generation, and guarded rollback | Short-lived App tokens, policy profiles, approval gates, signed evidence, and auditable decisions |
HawkOps is built on the proven Renovate engine and adds a GitHub-native control plane for security, remediation, and organization-wide coordination.
HawkOps is an automation and policy layer. It does not replace GitHub, package registries, CI, or a dedicated vulnerability scanner.
flowchart LR
A["GitHub events and schedules"] --> B["Scoped GitHub App token"]
B --> C["Dependency and repository analysis"]
C --> D{"Decision"}
D -->|Safe| E["Verified update PR"]
D -->|Review required| F["Evidence and reviewer gate"]
D -->|Blocked| G["Containment and remediation plan"]
E --> H["CI and canary"]
F --> H
H -->|Green| I["Human-approved merge"]
H -->|Failed| J["Bounded repair loop"]
J --> H
I --> K["Post-merge guardian"]
K -->|Regression| L["Rollback PR"]
- HawkOps discovers repository and dependency changes.
- It collects security, compatibility, policy, and repository evidence.
- It publishes one clear verdict: Safe, Review required, or Blocked.
- Approved changes run through repository CI and a bounded repair loop.
- Nothing merges without the configured GitHub checks and review policy.
| Area | What HawkOps does |
|---|---|
| Dependency intelligence | Correlates Dependabot, OSV, EPSS, CISA KEV, reachability, package reputation, licence policy, and OpenSSF signals |
| PR review | Detects likely bugs, unsafe code, secrets, excessive permissions, breaking changes, and missing tests |
| Autonomous remediation | Reads failed checks, applies bounded source or configuration repairs, refreshes lockfiles, reruns tests, and updates the PR |
| Migration engine | Applies reviewed recipes for JavaScript, TypeScript, React, Next.js, ESLint, PHP, Python, Docker, GitHub Actions, and database schemas |
| Multi-ecosystem coverage | Supports npm, Composer, Docker, GitHub Actions, Python, Maven, NuGet, and Renovate-compatible ecosystems |
| Zero-day response | Finds affected repositories, ranks exposure, contains confirmed risk, and opens review-gated emergency updates |
| Cross-repository coordination | Orders provider and consumer changes, links dependent PRs, and blocks unsafe rollout cycles |
| Repository Doctor | Reviews architecture, tests, CI, documentation, policy, permissions, and security posture |
| Supply-chain evidence | Produces SPDX, OpenVEX, SLSA provenance, attestations, and signed audit records |
| Post-merge protection | Watches the exact merged revision and opens a guarded rollback PR when a regression is confirmed |
HawkOps is deliberately conservative:
- installation tokens are scoped and short-lived;
- GitHub Actions are pinned to immutable commit digests;
- global automerge is disabled;
- major and elevated-risk updates require approval;
- missing evidence is reported as
unknown, never as a clean result; - repair attempts are file-scoped, bounded, and accepted only after tests pass;
- commands use an exact grammar and verify the author association;
- cross-repository rollouts are ordered and review-gated;
- every sensitive decision carries evidence and a rollback plan;
- regular automation runs on fresh GitHub-hosted Ubuntu runners; private forks can opt into the documented one-job self-hosted runner model;
- no external dashboard, event receiver, or runtime is required.
GitHub issues, checks, Actions, and pull requests remain the source of truth.
The public HawkOps repository uses fresh GitHub-hosted Ubuntu runners for validation, security scans, ChatOps, remediation, reports, and releases. This removes the operational dependency on an always-online personal runner while preserving one-job isolation. Digest-pinned Semgrep, OSV-Scanner, Trivy, Gitleaks, and TruffleHog remain the open-source security gates.
Private forks can still use the repository-scoped JIT architecture described in CI runner modes and the ephemeral runner runbook.
HawkOps does not depend on an external dashboard or long-running public service. Operators approve work in issues, trigger it through ChatOps or workflow dispatch, inspect evidence in checks and Actions, and review every code change in pull requests.
This keeps authorization, history, evidence, and rollback state beside the repositories they govern. See Distribution for the reusable GitHub-only installation model.
- Node.js 24 or newer
- GitHub CLI authenticated as an authorized maintainer
- Docker for local Renovate dry runs
- permission to create or install a GitHub App
gh repo clone MrBoodj011/HawkOps
cd HawkOps
npm ci
npm run checknpm install --global @mrboodj/hawk
hawk --helpThe CLI supports local inspection and evidence verification. Organization-wide automation additionally requires the GitHub App.
npm run register-appReview the requested permissions, install the App only on approved repositories, and store the App ID and private key in GitHub Actions variables and secrets. The guided setup never writes the private key to the repository.
Follow the complete setup guide before enabling write mode.
gh workflow run onboard.yml --repo MrBoodj011/HawkOps -f mode=dry-run
gh workflow run renovate.yml --repo MrBoodj011/HawkOps \
-f mode=dry-run \
-f log_level=info
gh workflow run health.yml --repo MrBoodj011/HawkOpsReview the planned scope, generated evidence, and repository selection before running apply mode.
Trusted repository collaborators operate HawkOps from GitHub issue comments.
| Command | Purpose |
|---|---|
/hawk status |
Show the current repository or organization state |
/hawk health |
Run a fresh organization health audit |
/hawk apply |
Apply checked updates from a dependency dashboard |
/hawk retry |
Retry a failed targeted update |
/hawk cancel |
Cancel queued or running maintenance |
/hawk explain <package> |
Explain risk, compatibility, reputation, and replacement evidence |
/hawk preview <package> |
Preview a package update without creating a branch |
/hawk doctor |
Run a full repository architecture and security review |
/hawk snooze <package> <days> |
Pause one package update for 1 to 90 days |
/hawk unsnooze <package> |
Remove a package pause |
/hawk freeze |
Stop new dependency branches for the repository |
/hawk unfreeze |
Resume dependency maintenance |
/hawk remediate <PR> |
Diagnose a failed dependency PR and run bounded repair |
/hawk rollback <PR> |
Open a guarded rollback PR |
/hawk rollback-last |
Roll back the latest merged trusted dependency update |
/hawk help |
List accepted commands |
Commands are permission-checked, repository-scoped, idempotent, and recorded in GitHub.
| Workflow | Purpose |
|---|---|
validate.yml |
Validate source, policy, workflows, tests, and dependencies |
oss-security.yml |
Run Semgrep, OSV, Trivy, and Gitleaks without private CodeQL |
security-audit.yml |
Audit workflow trust, App permissions, and parser safety |
runner-doctor.yml |
Verify the dedicated self-hosted runner and Docker isolation |
renovate.yml |
Discover repositories and maintain dependencies |
onboard.yml |
Connect repositories to central HawkOps policy |
github-events.yml |
Process trusted commands and review ready PRs |
health.yml |
Publish repository and organization health evidence |
zero-day.yml |
Detect and contain critical dependency exposure |
remediate.yml |
Diagnose failed checks and open a repaired PR |
cross-repo.yml |
Coordinate ordered multi-repository rollouts |
post-merge-guardian.yml |
Detect regressions after merge |
rollback.yml |
Open a review-gated revert PR |
provenance.yml |
Build SPDX, OpenVEX, SLSA, and attestation evidence |
release.yml |
Maintain release PRs, tags, notes, and package publication |
npm-publish.yml |
Publish through npm OIDC on the single GitHub-hosted job |
Write-capable workflows use concurrency controls, repository allowlists, and explicit dry-run or approval gates.
# Analyze an SBOM without network access
hawk scan --sbom sbom.spdx.json --offline
# Calculate cross-repository impact
hawk impact --input impact.json
# Inspect package reputation and risk
hawk research --input package-metadata.json
# Verify signed HawkOps evidence
hawk verify \
--envelope hawk-provenance.dsse.json \
--key security/hawk-report-signing-public-key.pubOnline scans can query OSV. Community analyzers and policy extensions run through the capability-limited Plugin SDK.
Repositories can use strict, balanced, or fast profiles through
.github/hawk-policy.json. Profiles control:
- update grouping and stability windows;
- licence and vulnerability thresholds;
- normal and security reviewers;
- canary commands and required checks;
- package pauses and blocked registries;
- merge-queue eligibility.
Read Policy profiles for the schema and examples.
.
|-- .github/workflows/ # GitHub-native automation
|-- assets/ # Product identity
|-- benchmarks/ # Reproducible benchmark corpus
|-- docs/ # Operator and security documentation
|-- examples/ # Integration examples
|-- governance/ # Organization policy and controls
|-- scripts/ # Runtime, CLI, reports, and tests
|-- sdk/ # Analyzer and policy Plugin SDK
|-- security/ # Verification keys and security evidence
|-- action.yml # Reusable GitHub Action
|-- config.js # Renovate runtime configuration
|-- default.json # Shared dependency policy
`-- package.json
Run the complete local gate:
npm ci
npm run check
npm audit --omit=dev --audit-level=highRun a read-only Renovate simulation:
RENOVATE_TOKEN=github_token npm run dry-runScope it to selected repositories:
RENOVATE_TOKEN=github_token \
RENOVATE_REPOSITORIES=MrBoodj011/CBS_Mail \
npm run dry-runNever commit tokens, private keys, installation IDs, or generated credentials.
| Guide | Scope |
|---|---|
| Setup | GitHub App registration, secrets, and first dry run |
| Zero-cost private CI | Self-hosted runner, open-source scans, budget guardrails, and npm publishing |
| Ephemeral runner | One-job JIT runner controller, isolation, rotation, and verification |
| Migration | Upgrade paths and legacy dashboard compatibility |
| Operations | Scheduling, incidents, retries, and recovery |
| Distribution | GitHub-only installation and package distribution |
| Permissions | Reviewed GitHub App permission contract |
| Policy | Repository profiles and enforcement |
| Intelligence | Risk evidence, confidence, and verdict rules |
| Migration engine | Supported repair and migration recipes |
| Multi-organization verification | Tenant isolation and onboarding checks |
| Production pilot | Protected external pilot and failure simulation |
| Repository Doctor | Architecture and security review contract |
| Cross-repository coordination | Ordered rollout and rollback safety |
| Project Memory | Repository-scoped learned conventions |
| Threat model | Trust boundaries and attack analysis |
| Security review | Verification evidence and external review gate |
| Roadmap | Delivery rules and planned work |
Report vulnerabilities through the repository's private Security advisory flow. Do not open a public issue for credentials, token handling, repository write access, or dependency execution vulnerabilities.
Read SECURITY.md and the threat model before reporting.
HawkOps is independently created and maintained by MrBoodj011.
The project is licensed under GPL-3.0-or-later. Renovate remains a separate upstream project under its own licence and project terms.
Review the evidence. Control the change. Ship with confidence.