Metadata-Version: 2.3
Name: cookiefarm
Version: 1.3.2
Summary: Python decorator for parallel exploit dispatch in Attack & Defense CTFs using the CookieFarm framework.
Author: ByteTheCookies
Author-email: ByteTheCookies <team@bytethecookies.org>
Requires-Dist: requests
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/ByteTheCookies/CookieFarm
Description-Content-Type: text/markdown

# 🍪 CookieFarm - Exploiter Manager

![Language](https://img.shields.io/badge/languages-Python-yellowgreen)
![Keywords](https://img.shields.io/badge/keywords-CTF%2C%20Exploiting%2C%20Attack%20Defense-red)
![License](https://img.shields.io/badge/license-MIT-blue)

> Python decorator for automating exploit execution in CTF Attack & Defense competitions

---

## 📦 What is it?

This package provides a **`@exploit_manager` decorator** designed to automate the parallel execution of exploits in CTF (*Attack & Defense*) settings, specifically for use with the [CookieFarm](https://github.com/BytesTheCookies/CookieFarm) project.

It handles:

* Authentication with the central server
* Retrieving team configuration
* Automatic flag parsing from `stdout`

> ⚠️ **Note:** This package is **not standalone**. It must be used together with the [CookieFarm client](https://github.com/BytesTheCookies/CookieFarm). The client provides the required APIs and team configurations.

---

## 📦 Installation

To install the package:
```bash
pip install --upgrade cookiefarm requests
```


## ⚙️ How it works

The `@exploit_manager` decorator takes care of:

* Calling your `exploit(ip, port, name_service, flag_ids)` function
* Retrieving the CookieFarm server configuration
* Fetching the full flag IDs JSON at every tick
* Normalizing competition-specific flag IDs structures into a per-team list
* Passing only the current team/service flag IDs to each exploit thread
* Capturing your exploit's `stdout`
* Parsing flags via regex
* Logging the result in JSON format, including: team ID, port, service name, and the flag found


---

## 🚀 Example usage

```python
from cookiefarm import exploit_manager
import requests

@exploit_manager
def exploit(ip, port, name_service, flag_ids):
    # flag_ids contains only the IDs for the current team and service
    for flag_id in flag_ids:
        response = requests.get(
            f"http://{ip}:{port}/",
            params={"id": flag_id},
        )

        # Just print the flag to stdout
        print(response.text)

# Run from the command line with arguments from CookieFarm
# python3 myexploit.py -s <server_address> -t <tick_time> -T <thread_number> -p <port> -n <name_service>
```

For execution, you have to pass the required arguments from the command line, which are provided by the CookieFarm client. The decorator will handle the rest.

```bash

python3 myexploit.py -s <server_address> -t <tick_time> -T <thread_number> -p <port> -n <name_service> -x [test mode]
```

| Argument | Description |
|----------|-------------|
| `-s` or `--server_address` | The address of the CookieFarm server |
| `-t` or `--tick_time` | The time interval for the exploit execution |
| `-T` or `--thread_number` | The number of threads to use for the exploit |
| `-p` or `--port_service` | The port to target for the exploit |
| `-n` or `--name_service` | The name of the service to exploit |
| `-x` or `--test` | Run in test mode against the configured NOP team |

---

## 🧩 Flag IDs normalization

Different Attack/Defense infrastructures may expose flag IDs with different JSON layouts. CookieFarm fetches the full flag IDs JSON at every tick and normalizes it locally according to the `shared.flagids_format` value configured on the server.

The exploit function always receives:

```python
flag_ids: list
```

This list contains only the flag IDs for the current team and the current service.

### Format syntax

The `flagids_format` path supports dynamic tokens:

* `[service]` — the service name passed with `-n` / `--name_service`
* `[team]` — the team key to iterate over
* `[id]` — the terminal node containing the flag IDs

Literal keys can be written directly in the path.

### CyberChallenge-style layout

Raw flag IDs:

```json
{
  "Service1": {
    "team_1": {
      "1": ["id-a"],
      "2": ["id-b"]
    }
  }
}
```

Server configuration:

```yaml
shared:
  url_flag_ids: "http://10.10.0.1/flagids"
  flagids_format: "[service].[team].[id]"
```

The exploit running against `Service1` and `team_1` receives:

```python
["id-a", "id-b"]
```

### Team-first layout

Raw flag IDs:

```json
{
  "team_1": {
    "Service1": ["id-a", "id-b"]
  }
}
```

Server configuration:

```yaml
shared:
  url_flag_ids: "http://172.168.1.0/flagids"
  flagids_format: "[team].[service].[id]"
```

The exploit running against `Service1` and `team_1` receives:

```python
["id-a", "id-b"]
```

### Nested layout with a literal key

Raw flag IDs:

```json
{
  "teams": [123, 456, 789],
  "flag_ids": {
    "service1": {
      "123": ["abc123", "def456"],
      "789": ["xxx", "yyy"]
    }
  }
}
```

Server configuration:

```yaml
shared:
  url_flag_ids: "http://example.local/flagids"
  flagids_format: "flag_ids.[service].[team].[id]"
```

The exploit running against `service1` and team `123` receives:

```python
["abc123", "def456"]
```

If `flagids_format` is omitted, CookieFarm uses:

```yaml
flagids_format: "[service].[team].[id]"
```

---

## 🛠️ Requirements

* Python ≥ 3.13
* Working CookieFarm client installed


---

## 📝 License

Distributed under the [MIT License](LICENSE). Feel free to use, modify, and contribute.

---

For any questions, suggestions, or issues, feel free to open a [GitHub issue](https://www.github.com/BytesTheCookies/CookieFarmExploiter)!

**Created with ❤️ by ByteTheCookies (feat. @0xMatte)**
