vardrrunner 0.28.0__tar.gz

vardrrunner-0.28.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Aquino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vardrrunner-0.28.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: vardrrunner
+Version: 0.28.0
+Summary: Local automation runner for the VardrSec product family
+Author: Jorge Aquino
+License: MIT License
+        
+        Copyright (c) 2026 Jorge Aquino
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/VardrSec/VardrRunner
+Project-URL: Repository, https://github.com/VardrSec/VardrRunner
+Project-URL: Changelog, https://github.com/VardrSec/VardrRunner/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/VardrSec/VardrRunner/issues
+Keywords: security,bug-bounty,recon,automation,cli,vardrsec
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: requests>=2.31
+Requires-Dist: keyring>=24
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: types-requests>=2.31; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Dynamic: license-file
+
+# VardrRunner
+
+**The local automation runner for the VardrSec product family.**
+
+VardrRunner runs your security tooling on *your* machine and syncs the results to a
+VardrSec backend (today: [VardrMap](https://github.com/VardrSec/VardrMap)) over HTTP.
+It is a thin, fast, dependency-light client: it polls the backend for queued scan jobs,
+claims them atomically, executes the tool locally, streams live progress back, uploads
+results, and heartbeats so the backend always knows which machines are online.
+
+> **Why local?** Recon and scanning tools belong on the operator's box — their bandwidth,
+> their IP, their tool versions. The backend orchestrates and stores; the runner does the
+> work. The two are fully decoupled and only ever exchange JSON.
+
+---
+
+## Features
+- **Job queue worker** — poll, atomically claim, execute, and report scan jobs
+- **Daemon mode** — `daemon start` runs a continuous background worker (poll every 5 s,
+  heartbeat every 60 s) with detached mode, PID file, and graceful shutdown
+- **Tool runners** — `httpx`, `subfinder`, `nuclei`, `nmap`, `dnsx`, `naabu` (more coming),
+  each capturing output into a timestamped run directory, every run bounded by a timeout
+- **Recon pipelines** — chain tools in one command: `recon` (subfinder → httpx → nuclei),
+  `deep` (adds dnsx resolution), `ports` (subfinder → dnsx → naabu), `quick`
+- **VardrGate authorization tests** — `vardrgate_api_test` jobs drive the local `vardrgate`
+  binary over a CLI/JSON contract and attach the sanitized result to the job. Identity
+  credentials may reference a secret (`value_env` / `value_keychain`) that is resolved on
+  the runner at execution time, so the secret never reaches the backend
+- **Importers** — pull existing `nuclei` / `httpx` output files into the backend
+- **Real heartbeat** — reports hostname, version, OS, and per-tool availability so the
+  backend's Bridge shows live machine status
+- **Live job events** — emits `started → targets_resolved → running → uploaded → done/failed`
+  so the backend Terminal shows real-time logs
+- **Preflight (`doctor`)** — one command validates the whole machine (creds, URL, perms,
+  auth, daemon, disk, tools, pipelines) and exits non-zero on actionable failures, for
+  scripting unattended/VPS provisioning
+- **Safe by default** — missing tools fail the job loudly, targets are normalized before
+  use, and the API key is stored locally with restrictive permissions
+
+## Requirements
+- Python **3.10+**
+- The external tools you intend to run, on your `PATH` (e.g. `httpx`, `subfinder`, `nuclei`, `nmap`, `dnsx`, `naabu`) — plus `vardrgate` if you run `vardrgate_api_test` jobs
+- A VardrSec backend URL and an API key (`vmap_…` for VardrMap)
+- VardrMap **≥ v0.22.0** as the backend — the runner calls `/engagements/*` (see [CHANGELOG](CHANGELOG.md) v0.27.0)
+
+## Install
+
+**From PyPI** (once published) — recommended via [pipx](https://pipx.pypa.io) for an isolated CLI:
+```bash
+pipx install vardrrunner      # or: pip install vardrrunner
+```
+
+**From a GitHub Release** (works today, before PyPI) — grab the wheel from the
+[latest release](https://github.com/VardrSec/VardrRunner/releases) (each is built in CI
+with a CycloneDX SBOM and a build-provenance attestation):
+```bash
+pipx install ./vardrrunner-<version>-py3-none-any.whl
+```
+> Releases are cut per `vX.Y.Z` tag, so the newest release can lag `main`. Compare the
+> release tag against [CHANGELOG.md](CHANGELOG.md) — if you need a version that has not
+> been tagged yet, install from source.
+
+**From source** (development):
+```bash
+git clone https://github.com/VardrSec/VardrRunner.git
+cd VardrRunner
+python -m venv venv
+.\venv\Scripts\Activate.ps1     # Windows  (macOS/Linux: source venv/bin/activate)
+pip install -e ".[dev]"
+```
+All three install the `vardrrunner` command.
+
+> Homebrew / Scoop formulae are planned once there's demand; until then use pipx or the release wheel.
+
+## Quick start
+```bash
+vardrrunner login vardrmap     # prompts for backend URL + API key; key goes to your OS keychain
+vardrrunner status             # show config, version, and which tools are detected
+vardrrunner heartbeat          # confirm the backend can see this machine
+vardrrunner daemon start       # run the continuous worker (poll jobs + heartbeat)
+```
+
+### One-shot usage
+```bash
+vardrrunner engagements                                       # list your engagements
+vardrrunner scope <engagement-id>                             # show in/out-of-scope items
+vardrrunner jobs list                                         # show the backend queue
+vardrrunner jobs run                                          # claim + execute all pending jobs once
+vardrrunner run subfinder --engagement <engagement-id>        # run a single tool and upload results
+vardrrunner import nuclei --engagement <engagement-id> -f out.jsonl
+```
+`--engagement` takes the engagement UUID; `--program` and `-p` are accepted as aliases.
+
+See **[docs/cli.md](docs/cli.md)** for the full command reference.
+
+## Configuration
+
+**Desktop / dev:** `vardrrunner login` stores your API key in the **OS keychain** (macOS
+Keychain, Windows Credential Locker, Linux Secret Service) — no plaintext key on disk. The
+backend URL is kept in `~/.vardrmap/config.json`. Run `vardrrunner logout` to remove it.
+
+**CI / servers / containers:** set credentials via environment variables (no keychain
+needed). The key resolves in this order — **`VARDRMAP_API_KEY` env → OS keychain → config
+file**:
+
+| Variable | Purpose |
+|----------|---------|
+| `VARDRMAP_URL` | Backend base URL (must be `https://`, except `localhost`) |
+| `VARDRMAP_API_KEY` | Your `vmap_` API key |
+| `VARDRRUNNER_TOOL_TIMEOUT` | Per-tool run timeout in seconds (default 1800); a hung tool is killed and the job marked failed |
+| `VARDRRUNNER_ALLOW_INSECURE` | Set to `1` to permit a plain-HTTP backend URL (not recommended) |
+
+The runner refuses to send your API key over plain HTTP to a non-local host, so a mistyped
+`http://` URL can't leak your key.
+
+## Documentation
+- [docs/architecture.md](docs/architecture.md) — how the runner is structured and how it talks to the backend
+- [docs/development.md](docs/development.md) — local setup, testing, and contribution workflow
+- [docs/cli.md](docs/cli.md) — complete command and flag reference
+- [docs/adr/](docs/adr/) — Architecture Decision Records
+- [CHANGELOG.md](CHANGELOG.md) — version history
+
+## Development & testing
+```bash
+pip install -e ".[dev]"   # editable install + dev tools (pytest, ruff, mypy)
+ruff check vardrrunner tests           # lint
+ruff format --check vardrrunner tests  # formatting
+mypy vardrrunner                       # type check
+pytest tests              # 450 tests; all subprocess + HTTP calls are mocked
+```
+CI runs ruff (lint + format), mypy, and a bandit security scan, then the test suite at a
+95% coverage floor on Python 3.10/3.11/3.12 (Linux) plus a 3.12 smoke on Windows and
+macOS, and a `pip-audit` dependency audit — on every push and PR to `main`.
+Contributions follow the **Engineering Charter** in [CLAUDE.md](CLAUDE.md): clean code,
+tests in the same commit, docs updated, and the suite always green.
+
+## License
+[MIT](LICENSE) © 2026 Jorge Aquino.
+
+---
+*Part of the VardrSec product family — [VardrMap](https://github.com/VardrSec/VardrMap) · VardrRunner · VardrVault.*

vardrrunner-0.28.0/README.md

@@ -0,0 +1,141 @@
+# VardrRunner
+
+**The local automation runner for the VardrSec product family.**
+
+VardrRunner runs your security tooling on *your* machine and syncs the results to a
+VardrSec backend (today: [VardrMap](https://github.com/VardrSec/VardrMap)) over HTTP.
+It is a thin, fast, dependency-light client: it polls the backend for queued scan jobs,
+claims them atomically, executes the tool locally, streams live progress back, uploads
+results, and heartbeats so the backend always knows which machines are online.
+
+> **Why local?** Recon and scanning tools belong on the operator's box — their bandwidth,
+> their IP, their tool versions. The backend orchestrates and stores; the runner does the
+> work. The two are fully decoupled and only ever exchange JSON.
+
+---
+
+## Features
+- **Job queue worker** — poll, atomically claim, execute, and report scan jobs
+- **Daemon mode** — `daemon start` runs a continuous background worker (poll every 5 s,
+  heartbeat every 60 s) with detached mode, PID file, and graceful shutdown
+- **Tool runners** — `httpx`, `subfinder`, `nuclei`, `nmap`, `dnsx`, `naabu` (more coming),
+  each capturing output into a timestamped run directory, every run bounded by a timeout
+- **Recon pipelines** — chain tools in one command: `recon` (subfinder → httpx → nuclei),
+  `deep` (adds dnsx resolution), `ports` (subfinder → dnsx → naabu), `quick`
+- **VardrGate authorization tests** — `vardrgate_api_test` jobs drive the local `vardrgate`
+  binary over a CLI/JSON contract and attach the sanitized result to the job. Identity
+  credentials may reference a secret (`value_env` / `value_keychain`) that is resolved on
+  the runner at execution time, so the secret never reaches the backend
+- **Importers** — pull existing `nuclei` / `httpx` output files into the backend
+- **Real heartbeat** — reports hostname, version, OS, and per-tool availability so the
+  backend's Bridge shows live machine status
+- **Live job events** — emits `started → targets_resolved → running → uploaded → done/failed`
+  so the backend Terminal shows real-time logs
+- **Preflight (`doctor`)** — one command validates the whole machine (creds, URL, perms,
+  auth, daemon, disk, tools, pipelines) and exits non-zero on actionable failures, for
+  scripting unattended/VPS provisioning
+- **Safe by default** — missing tools fail the job loudly, targets are normalized before
+  use, and the API key is stored locally with restrictive permissions
+
+## Requirements
+- Python **3.10+**
+- The external tools you intend to run, on your `PATH` (e.g. `httpx`, `subfinder`, `nuclei`, `nmap`, `dnsx`, `naabu`) — plus `vardrgate` if you run `vardrgate_api_test` jobs
+- A VardrSec backend URL and an API key (`vmap_…` for VardrMap)
+- VardrMap **≥ v0.22.0** as the backend — the runner calls `/engagements/*` (see [CHANGELOG](CHANGELOG.md) v0.27.0)
+
+## Install
+
+**From PyPI** (once published) — recommended via [pipx](https://pipx.pypa.io) for an isolated CLI:
+```bash
+pipx install vardrrunner      # or: pip install vardrrunner
+```
+
+**From a GitHub Release** (works today, before PyPI) — grab the wheel from the
+[latest release](https://github.com/VardrSec/VardrRunner/releases) (each is built in CI
+with a CycloneDX SBOM and a build-provenance attestation):
+```bash
+pipx install ./vardrrunner-<version>-py3-none-any.whl
+```
+> Releases are cut per `vX.Y.Z` tag, so the newest release can lag `main`. Compare the
+> release tag against [CHANGELOG.md](CHANGELOG.md) — if you need a version that has not
+> been tagged yet, install from source.
+
+**From source** (development):
+```bash
+git clone https://github.com/VardrSec/VardrRunner.git
+cd VardrRunner
+python -m venv venv
+.\venv\Scripts\Activate.ps1     # Windows  (macOS/Linux: source venv/bin/activate)
+pip install -e ".[dev]"
+```
+All three install the `vardrrunner` command.
+
+> Homebrew / Scoop formulae are planned once there's demand; until then use pipx or the release wheel.
+
+## Quick start
+```bash
+vardrrunner login vardrmap     # prompts for backend URL + API key; key goes to your OS keychain
+vardrrunner status             # show config, version, and which tools are detected
+vardrrunner heartbeat          # confirm the backend can see this machine
+vardrrunner daemon start       # run the continuous worker (poll jobs + heartbeat)
+```
+
+### One-shot usage
+```bash
+vardrrunner engagements                                       # list your engagements
+vardrrunner scope <engagement-id>                             # show in/out-of-scope items
+vardrrunner jobs list                                         # show the backend queue
+vardrrunner jobs run                                          # claim + execute all pending jobs once
+vardrrunner run subfinder --engagement <engagement-id>        # run a single tool and upload results
+vardrrunner import nuclei --engagement <engagement-id> -f out.jsonl
+```
+`--engagement` takes the engagement UUID; `--program` and `-p` are accepted as aliases.
+
+See **[docs/cli.md](docs/cli.md)** for the full command reference.
+
+## Configuration
+
+**Desktop / dev:** `vardrrunner login` stores your API key in the **OS keychain** (macOS
+Keychain, Windows Credential Locker, Linux Secret Service) — no plaintext key on disk. The
+backend URL is kept in `~/.vardrmap/config.json`. Run `vardrrunner logout` to remove it.
+
+**CI / servers / containers:** set credentials via environment variables (no keychain
+needed). The key resolves in this order — **`VARDRMAP_API_KEY` env → OS keychain → config
+file**:
+
+| Variable | Purpose |
+|----------|---------|
+| `VARDRMAP_URL` | Backend base URL (must be `https://`, except `localhost`) |
+| `VARDRMAP_API_KEY` | Your `vmap_` API key |
+| `VARDRRUNNER_TOOL_TIMEOUT` | Per-tool run timeout in seconds (default 1800); a hung tool is killed and the job marked failed |
+| `VARDRRUNNER_ALLOW_INSECURE` | Set to `1` to permit a plain-HTTP backend URL (not recommended) |
+
+The runner refuses to send your API key over plain HTTP to a non-local host, so a mistyped
+`http://` URL can't leak your key.
+
+## Documentation
+- [docs/architecture.md](docs/architecture.md) — how the runner is structured and how it talks to the backend
+- [docs/development.md](docs/development.md) — local setup, testing, and contribution workflow
+- [docs/cli.md](docs/cli.md) — complete command and flag reference
+- [docs/adr/](docs/adr/) — Architecture Decision Records
+- [CHANGELOG.md](CHANGELOG.md) — version history
+
+## Development & testing
+```bash
+pip install -e ".[dev]"   # editable install + dev tools (pytest, ruff, mypy)
+ruff check vardrrunner tests           # lint
+ruff format --check vardrrunner tests  # formatting
+mypy vardrrunner                       # type check
+pytest tests              # 450 tests; all subprocess + HTTP calls are mocked
+```
+CI runs ruff (lint + format), mypy, and a bandit security scan, then the test suite at a
+95% coverage floor on Python 3.10/3.11/3.12 (Linux) plus a 3.12 smoke on Windows and
+macOS, and a `pip-audit` dependency audit — on every push and PR to `main`.
+Contributions follow the **Engineering Charter** in [CLAUDE.md](CLAUDE.md): clean code,
+tests in the same commit, docs updated, and the suite always green.
+
+## License
+[MIT](LICENSE) © 2026 Jorge Aquino.
+
+---
+*Part of the VardrSec product family — [VardrMap](https://github.com/VardrSec/VardrMap) · VardrRunner · VardrVault.*

vardrrunner-0.28.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vardrrunner"
+dynamic = ["version"]
+description = "Local automation runner for the VardrSec product family"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Jorge Aquino" }]
+keywords = ["security", "bug-bounty", "recon", "automation", "cli", "vardrsec"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "requests>=2.31",
+    "keyring>=24",
+]
+
+[project.urls]
+Homepage = "https://github.com/VardrSec/VardrRunner"
+Repository = "https://github.com/VardrSec/VardrRunner"
+Changelog = "https://github.com/VardrSec/VardrRunner/blob/main/CHANGELOG.md"
+Issues = "https://github.com/VardrSec/VardrRunner/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "types-requests>=2.31",
+    "bandit>=1.7",
+]
+
+[project.scripts]
+vardrrunner = "vardrrunner.cli:app"
+
+# Single source of truth for the version: read the literal from the package.
+[tool.setuptools.dynamic]
+version = { attr = "vardrrunner.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["vardrrunner*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+# E/W pycodestyle, F pyflakes, I import-sorting, B bugbear, UP pyupgrade.
+select = ["E", "W", "F", "I", "B", "UP"]
+ignore = [
+    # Long lines are left to the formatter; do not fail lint on E501.
+    "E501",
+    # B008: function call in argument default. This is the required Typer idiom
+    # (`typer.Option(...)` / `typer.Argument(...)` as defaults) — not a bug here.
+    "B008",
+]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+# warn_unused_ignores is intentionally OFF: Windows-only `# type: ignore`s (ctypes.windll,
+# DETACHED_PROCESS) are needed when CI type-checks on Linux but unused on Windows.
+# Pragmatic baseline — not strict mode. Tighten incrementally over time.
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

vardrrunner-0.28.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+