# offsec — Changelog

## v1.0.0 — 2026-06-23

Initial release. First of six **category dispatchers** for the
cli.johlem.net suite. Sister dispatchers (queued, identical recipe):
`blueteam`, `opsec`, `grc`, `recon`, `util`.

### What it is

A ~1 MB router binary that wraps the offensive half of the suite
(13 tools: urlrecon, webharvest, payloadforge, lexharvest, credsweep,
regexlab, b64chain, hashcrackref, mailforge, wifiaudit, vlanrecon,
esptools, pentree) behind a single front door, **without merging the
underlying binaries**. Every tool stays separately installable,
separately signify-signed, and separately versioned. offsec just:

1. shows you what offensive tools exist (`offsec`, `offsec list`),
2. tells you which are installed (`offsec doctor`),
3. forwards subcommands to the right binary (`offsec urlrecon …`),
4. helps install missing ones (`offsec install --all`).

### Subcommands

```
offsec                          # short tabular listing
offsec list   [-F human|json] [--installed]
offsec doctor [-F human|json]
offsec search <query> [-F human|json]
offsec install [--all] [<tool>...]
offsec <tool> [args...]         # forwarded via external_subcommand
```

### Catalogue resolution

The dispatcher reads the suite catalogue in this order:

1. `$OFFSEC_CATALOGUE` (env override — primarily for tests).
2. `$XDG_DATA_HOME/cli-johlem/catalogue.json` (live copy `jcli update`
   refreshes — keeps the listing current without rebuilding offsec).
3. Vendored snapshot baked in at compile time (works offline, on a
   fresh install, with no network and no jcli refresh).

`offsec doctor` prints which source was loaded.

### Forwarding semantics

`offsec urlrecon --headers https://target.example.com` is rewritten
through clap's `external_subcommand` mechanism into `urlrecon
--headers https://target.example.com`. The wrapped tool's stdout,
stderr, and **exit code** flow through unchanged — so existing
pipelines that key off `urlrecon` exiting `1` on findings keep
working when invoked via the dispatcher.

Binary lookup order:

1. `$XDG_BIN_HOME/<tool>`
2. `~/.local/bin/<tool>` (jcli's default install path)
3. `<tool>` on `$PATH`

### Why a dispatcher, not a merged binary?

Considered and rejected during 2026-06-23 architecture review:

| Merge into one binary | Dispatcher (this release) |
|---|---|
| ~35 MB binary, 50 ms cold start | ~1 MB binary, ~5 ms cold start |
| One semver bumps for any tool's bug fix | Per-tool semver preserved |
| `cap_net_admin` on the whole binary | Per-tool capabilities (wifiaudit only) |
| Plugin support needs dlopen + cdylib boundaries | Adding a tool = drop a slug into catalogue.json |
| Breaks pre-commit / CI invocations | `credsweep` etc. keep their original entry point |

Each underlying tool is unchanged.

### Build

- Library crate (`offsec`) + thin CLI binary.
- 3 unit tests (catalogue parsing, search, lookup) + 14 integration
  tests (every subcommand + forwarding + env override). Zero compiler
  warnings.
- Suite-standard exit codes per `SUITE_STANDARDS.md` §1:
  0 ok · 1 doctor found missing tools / no search hits · 2 usage ·
  3 runtime · `*` forwarded tool's own exit code (passes through).
- Mandatory tagline footer on every `--help`:
  `[ offsec ] ─ an independent project by johlem.net`.
- `--full` extended help with full per-tool catalogue table.

### Deferred to v1.1

- `offsec init` — install missing offsec tools + drop curated config.
- `offsec graph` — visualise which tools feed which (jfind/v1 producer
  → consumer chains).
- Shell completions (bash / zsh / fish) listing the contained tools.
- Cross-dispatcher search: `offsec search wifi --all-apps` checks
  every category.