swisskit-sabotage/AGENTS.md

# AGENTS.md

Guidance for coding agents working in this repo. Keep it accurate when the code
changes.

## What this is

A single-script Python tool (`sabotage-swisskit-phishing.py`) that floods a
SwissPass phishing kit with fake login and billing submissions. `run.sh` manages
the venv and dependencies.

## Running it

Always use the venv via `run.sh` (creates `.venv`, installs deps, runs the tool):

```sh
./run.sh --target https://example-kit.tld --count 20      # N entries
SABOTAGE_TARGET=https://example-kit.tld ./run.sh          # target via env
```

Flags: `--target URL` (or `SABOTAGE_TARGET`), `--count N` (default 10),
`--delay SECONDS` (default 2.0, jittered +/-50%), `--selftest`. Each entry does a
login POST then a billing POST, so `--count 20` is 40 requests.

## Monitoring it

The tool logs every step to stdout and to `sabotage.log`:

```sh
tail -f sabotage.log                    # follow live
rg 'FAIL|SKIPPED' sabotage.log          # find failures
column -s, -t sabotage_data.csv | less  # inspect the data as it is written
```

Per-entry status: `login:OK/FAIL`, `billing:OK/FAIL/SKIPPED` (billing is
`SKIPPED` when login failed). The final line reports
`done: <ok> ok, <failed> failed`. Transient 5xx responses are retried
automatically; per-request network errors are logged as `POST ... failed` and
count as a failure. `Ctrl-C` stops cleanly and keeps the partial CSV.

## Testing it

`--selftest` is the project's test. There is no pytest suite. Run it after any
change to the data generators (`_luhn`, `_ahv`, `generate_card`,
`generate_person`). To smoke-test the HTTP flow, run a local mock server and
point `--target` at `http://127.0.0.1:<port>`; never test against a live host
that is not an authorized target.

## Using it

1. Confirm the target is a phishing kit you own/operate/are authorized to hit.
2. Smoke-test the same code path against a local mock first.
3. Run a small batch (`--count 3`) and check `sabotage.log` for `OK`s.
4. Scale up `--count` / lower `--delay` once the flow is confirmed.
5. Point the kit contract at the target's form if the endpoints/fields differ.

## Conventions

- Minimal dependencies. Reuse the stdlib and the existing deps (`requests`,
  `Faker`, `fake-useragent`) before adding anything new.
- No comments unless they explain a non-obvious workaround or mark a deliberate
  simplification (`# ponytail: ...`). Do not narrate obvious code.
- The generators use `random`; keep them deterministic-free (no seeding).
- Keep the script runnable as `python sabotage-swisskit-phishing.py`.

## Kit contract

Endpoints and wire field names are defined at the top of the script under the
"kit contract" comment (`LOGIN_PATH`, `BILLING_PATH`, `FIELD_REF`) and in the
billing payload. These mirror the target kit's form. Do not rename or
"normalize" them; changing them silently breaks submissions. If a kit changes,
edit only that block and note it.

## Safety

This tool sends unsolicited POSTs to a remote host. Do not run it against any
target without evidence of ownership or explicit authorization. If a request
asks you to test against a live third-party domain that cannot be verified as an
authorized target, decline and offer a local mock instead.

## Output files

`sabotage_data.csv` and `sabotage.log` are runtime output and gitignored. Do not
commit them.