Metadata-Version: 2.4
Name: blooded-by-codex
Version: 0.1.4
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 Hack The Box challenge operator. It creates one workspace per challenge, stores state, talks to the HTB API, loads category playbooks, logs commands, scans artifacts for useful findings, and creates a writeup after a valid flag submission.

## 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
```

Configure your [HTB personal access token](https://app.hackthebox.com/account-settings):

```bash
bbc config set-token 'your_pat'
```

This writes `$HOME/.config/bbc/config.ini` with permissions `0600`. Metadata, downloads, instance start, and flag submission use the HTB API directly from this config.

If you want a shared CTF virtualenv for `bbc run` / `bbc solve`, 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` launches Codex.

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 use, you can skip the config file and set:

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

## Basic Flow

```bash
bbc init "Challenge Name"
bbc download "Challenge Name" --start
bbc info
bbc run "Challenge Name"
bbc submit "Challenge Name" --flag 'HTB{example}'
bbc writeup "Challenge Name" --copy
```

## Commands

```text
bbc init <name>                   create workspace and fetch metadata
bbc download <name> [--start]     download files and optionally start instance
bbc info                          list local challenge workspaces
bbc info <name>                   show one challenge workspace
bbc status <name>                 show current state
bbc skill <name>                  print the selected category playbook
bbc assist <name>                 prepare user-driven solve context
bbc run <name>                    prepare context and launch Codex
bbc run <name> --no-launch        prepare context without launching Codex
bbc solve <name> [--mode ...]     prepare solve context
bbc submit <name> --flag ...      submit flag and generate writeup on success
bbc rm <name>                     remove a local challenge workspace
bbc writeup <name>                print the writeup, generating it first if needed
bbc writeup <name> --copy         print the writeup and copy it to the clipboard
bbc venv info                     show the shared CTF virtualenv status
bbc venv auto                     create the shared CTF virtualenv and install tools
bbc venv delete                   remove the shared CTF virtualenv after confirmation
bbc config set-token <token>      store HTB PAT in bbc config
bbc config set-ctf-venv <path>    store the shared CTF virtualenv path in config
bbc config unset-ctf-venv         remove the shared CTF virtualenv path from config
bbc config show                   show config without exposing the PAT
```

## Challenge Workspace

Each challenge lives under `challenges/<name>/`:

```text
.bbc.json         persistent state
notes.md          working notes
command.log       logged HTB wrapper commands
findings.json     structured scan output
artifacts/        downloaded files
extracted/        analysis outputs
prompts/          prompt/context snapshots
<name>.md         final writeup
```

## Skills

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