Metadata-Version: 2.4
Name: blooded-by-codex
Version: 0.1.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 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.

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 scan "Challenge Name"
bbc run "Challenge Name"
bbc submit "Challenge Name" --flag 'HTB{example}'
```

## Commands

```text
bbc init <name>                   create workspace and fetch metadata
bbc download <name> [--start]     download files and optionally start instance
bbc scan <name>                   refresh file inventory and candidate flags
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 writeup <name>                generate writeup from current notes and logs
bbc config set-token <token>      store HTB PAT in bbc 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`.
