Metadata-Version: 2.4
Name: blooded-by-codex
Version: 0.2.0
Summary: A Hack The Box challenge operator with Codex-oriented logs, skills, and writeups.
License-Expression: MIT
Project-URL: Homepage, https://github.com/nomaisthere/blooded-by-codex
Project-URL: Repository, https://github.com/nomaisthere/blooded-by-codex
Project-URL: Issues, https://github.com/nomaisthere/blooded-by-codex/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Blooded by Codex

Have you ever seen HTB challenges that get cleared in 15s ? And been sad it wasnt you ?  
Well, the **bbc** will change your life!  

`bbc` (blooded-by-codex) is a small workspace-based CTF challenge operator. Each workspace has its own provider config, flag format, and challenge folders. `bbc` prepares Codex solve context, downloads artifacts, starts remote targets when supported, submits flags, and creates a writeup after success.

This project is purely made out of sadness: finding pleasure in knowledge acquirement while AI knows everything is hard. It's a troll project, don't take it too seriously.  
It mostly was made to understand how PyPI packaging worked.

## Install

```bash
pipx install blooded-by-codex
```

Or with `uv`:

```bash
uv tool install blooded-by-codex
```

If you want to run from a local checkout instead:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e . --no-build-isolation
./bbc --help
```

Create a workspace with its own provider config. For HTB, use your [HTB personal access token](https://app.hackthebox.com/account-settings):

```bash
bbc workspace create htb-main --provider htb --token 'your_pat'
bbc workspace use htb-main
```

Each workspace is a folder under `workspaces/` and has its own `.bbc-workspace.ini` with provider type, redacted auth config, and flag format. The shared global config at `$HOME/.config/bbc/config.ini` only tracks the current workspace and shared CTF venv path.

If you want a shared CTF virtualenv for `bbc run` / `bbc blood`, create it with:

```bash
bbc venv auto
bbc config show
```

That creates a shared venv at `~/.local/share/bbc/ctf-venv` by default, installs the bundled CTF requirements, saves the path in `~/.config/bbc/config.ini`, and prepends its `bin/` directory to `PATH` when `bbc run` or `bbc blood` launches Codex.

If you want a first-blood style run with live web search and no approval pauses, use `bbc blood`. It launches Codex with `--dangerously-bypass-approvals-and-sandbox` and `--search`, so it can execute and submit immediately. That is intentionally high risk.

You can also manage the venv path explicitly in config:

```bash
bbc config set-ctf-venv ~/my-ctf-venv
bbc config unset-ctf-venv
bbc config show
```

For temporary HTB use, you can still override the workspace token with:

```bash
export BBC_HTB_API_KEY='your_pat'
```

For temporary CTFd use, you can override the workspace credentials with:

```bash
export BBC_CTFD_API_KEY='your_ctfd_token'
export BBC_CTFD_BASE_URL='https://ctfd.example.com/'
```

## Basic Flow

```bash
bbc workspace create htb-main --provider htb --token 'your_pat'
bbc workspace use htb-main
bbc challenge create "Challenge Name"
bbc feed "Challenge Name" ~/writeups/similar-forensics-case
bbc feed list "Challenge Name"
bbc feed rm "Challenge Name" 1
bbc guess "Challenge Name" ~/notes/challenge-guess.md
bbc challenge download "Challenge Name" --start
bbc challenge list
bbc run "Challenge Name"
bbc blood "Challenge Name"
bbc submit "Challenge Name" --flag 'HTB{example}'
bbc writeup "Challenge Name" --copy
bbc export "Challenge Name"
bbc export "Challenge Name" --full
bbc doctor
bbc reference pack "Challenge Name"
```

## Commands

```text
bbc workspace create <name> [--provider ... --token ... --format ...]
bbc workspace list
bbc workspace use <name>
bbc workspace show [name]
bbc challenge create <name>
bbc challenge list
bbc challenge show <name>
bbc challenge download <name> [--start]
bbc challenge rm <name>
bbc feed <name> <path> [--label ...]
bbc feed add <name> <path> [--label ...]
bbc feed list <name>
bbc feed rm <name> <selector>
bbc guess <name> <path>
bbc export <name>
bbc export <name> --full
bbc doctor [--workspace ...]
bbc reference pack <name> [--force]
bbc run <name>
bbc run <name> --no-launch
bbc blood <name>
bbc blood <name> --no-launch
bbc submit <name> --flag ...
bbc writeup <name>
bbc writeup <name> --copy
bbc venv info
bbc venv auto
bbc venv delete
bbc config set-ctf-venv <path>
bbc config unset-ctf-venv
bbc config show
```

## Workspace Layout

Each workspace lives under `workspaces/<workspace>/`:

```text
.bbc-workspace.ini        provider, token, base URL, flag prefix
challenges/<name>/        one local folder per challenge
```

Each challenge inside a workspace contains:

```text
.bbc.json                 persistent state
notes.md                  working notes
command.log               logged commands
findings.json             structured scan output
artifacts/                downloaded files
extracted/                analysis outputs
guess.md                  human guess or hypothesis for the challenge direction
references/               copied writeups, notes, or prior challenge material fed into Codex
prompts/                  prompt/context snapshots
<name>.md                 final writeup
```

Use `bbc feed <challenge> <path>` to attach a file or directory as reference material. `bbc` copies that data into the challenge `references/` folder and refreshes `prompts/runtime_context.md` immediately, so a running Codex session can pick it up from disk without you pasting it into chat.

Use `bbc feed list <challenge>` to inspect attached references, and `bbc feed rm <challenge> <selector>` to remove one by index, label, or stored path.

Use `bbc guess <challenge> <path/to/guess.md>` to copy a human hypothesis into `guess.md` in the challenge root. That file is called out separately in the solve context and runtime context, so Codex can treat it as a lead to verify rather than as authoritative evidence.

Use `bbc export <challenge>` to create `<challenge>-solve.zip` in the challenge root. The archive packages the current writeup, notes, command log, findings, guess, references, `.bbc.json`, and the solve/runtime prompt context so the solve can be handed off or archived cleanly.

Use `bbc export <challenge> --full` to create `<challenge>-solve-full.zip`, which also includes `artifacts/` and `extracted/`.

Use `bbc doctor` to check local config, workspace state, provider settings, skills path, and shared venv setup.

Use `bbc reference pack <challenge>` to build a reusable directory under `reference-packs/` from a solved or in-progress challenge. That pack can later be fed into another challenge with `bbc feed`.

## Providers

The provider boundary is now explicit. `htb` and `ctfd` are both implemented.

Current CTFd support covers:
- challenge lookup by exact name or numeric id
- challenge detail fetch
- artifact download from returned file URLs
- remote target capture from `connection_info`
- flag submission through `/api/v1/challenges/attempt`

Some CTFd deployments may be opinionated about headers. The `ctfd-test` instance used during development required both `Accept: application/json` and `Content-Type: application/json` even for authenticated `GET` requests.

## Skills

Category guidance lives in `skills/`. The current categories are `web`, `crypto`, `reversing`, `pwn`, `forensics`, and `misc`.
