Metadata-Version: 2.4
Name: ctf-attackapi
Version: 0.1.0
Summary: Get attack infos in attack-defense CTFs quickly to your exploits. CTF-agnostic and cached.
Keywords: Attack-Defense,CTF,Attack API,Attack Info,Flag IDs,FAUST CTF,ENOWARS,saarCTF
Author: Markus Bauer
Author-email: Markus Bauer <markus.bauer@cispa.saarland>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Security
Classifier: Typing :: Typed
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: aiologic>=0.16.0
Requires-Dist: filelock>=3.19.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: gunicorn>=23.0.0 ; extra == 'server'
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/Attacking-Lab/ctf-attackapi
Project-URL: Repository, https://github.com/Attacking-Lab/ctf-attackapi
Project-URL: Issues, https://github.com/Attacking-Lab/ctf-attackapi/issues
Project-URL: Background, https://wiki.attacking-lab.com/attack-defense/
Provides-Extra: server
Description-Content-Type: text/markdown

CTF AttackAPI - Cached and Unified!
===================================

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/license/mit)
![Python](https://img.shields.io/pypi/pyversions/ctf-attackapi?pypiBaseUrl=https://test.pypi.org)
![Types](https://img.shields.io/pypi/types/ctf-attackapi?pypiBaseUrl=https://test.pypi.org)
[![Python package tests](https://github.com/Attacking-Lab/ctf-attackapi/actions/workflows/python-package.yml/badge.svg)](https://github.com/Attacking-Lab/ctf-attackapi/actions/workflows/python-package.yml)
[![PyPI version](https://img.shields.io/pypi/v/ctf-attackapi?pypiBaseUrl=https://test.pypi.org)](https://pypi.org/project/ctf-attackapi)
![Downloads](https://img.shields.io/pypi/dm/ctf-attackapi?pypiBaseUrl=https://test.pypi.org)
![Repo size](https://img.shields.io/github/repo-size/Attacking-Lab/ctf-attackapi)


Gather attack information quickly in your attack-defense CTF exploits!

During [attack-defense CTF competitions](https://wiki.attacking-lab.com/attack-defense/), you have to write exploits
quickly and run them on a large scale.
These exploits often require information about the targets to attack (teams and sometimes usernames).
This attack info is available as a big JSON file which is updated every few minutes.
Downloading that file for every exploit you're firing is costing time and bandwidth.

This package fetches, parses, and caches attack info for you, so you can focus on writing exploits!

Features
--------

- Efficient caching between threads, processes, or containers
- Direct access from your Python exploits ([sync](./examples/basic.py) or [async](./examples/basic_async.py))
- Optional REST API for exploits in other languages (with [OpenAPI spec](./api.yaml))
- Unifies team, IP, and flag info lookup between different CTFs:
    - Supports [ENOWARS](https://enowars.com)
    - Supports [FAUST CTF](https://faustctf.net)
    - Supports [saarCTF](https://ctf.saarland) (including ECSC gameserver)

Quick-Start
-----------
See [examples](./examples) directory for more full scripts.

Install the package (possibly in a virtual environment):

```shell
pip install ctf-attackapi
```

Get attack infos for your python exploit:

```python
from attackapi import *

# 1. Set the API URL in code (or use CTF_API environment variable)
configure("https://scoreboard.ctf.saarland/api/attack.json")
# 2. Get attack infos!
for username in attack_info().flag_id_flat("no-service", "10.32.1.2"):
  pwn("10.32.1.2", username)
```

List all teams that you can attack:

```python
from attackapi import *

configure("https://scoreboard.ctf.saarland/api/attack.json")
for team in attack_info().teams:
  print(team.id, team.ip, team.name)
```

Get attack infos from REST API if you're not pwning in Python:

```shell
python -m attackapi.server --url "https://scoreboard.ctf.saarland/api/attack.json"
curl "http://localhost:14320/api/v1/teams"
```

The server has documentation on its frontpage, and here is [the OpenAPI specification](./api.yaml).

If you're not pwning in Python and dislike pip, try docker:
```shell
# edit compose.yaml and insert your CTF API URL
docker compose up -d
# visit http://localhost:14320/
```


Structure
---------

- Attack info data is retrieved and cached twice: in-memory and on disk (`/tmp` by default)
- Each request goes to the caches. If the cached data is outdated, it is refreshed in the background.
- No concurrent requests are made to the game API.
- Game-specific decoders process the game APIs data and make it accessible.
- You can query the data via python API from your exploits, or via REST API from other languages.
- Relying on the disk cache is good enough for typical exploitation scenarios.

Python Library Documentation
----------------------------
There are different ways to get an `AttackInfo` object:

```python
# 1. Functional
from attackapi import *

# Set the API URL in code (or use CTF_API environment variable)
configure("https://scoreboard.ctf.saarland/api/attack.json")
# sync:
info: AttackInfo = attack_info()
# async
info: AttackInfo = await attack_info_async()

# 2. By manually using the classes
from attackapi.sync_api import AdCtfApiSync
from attackapi.async_api import AdCtfApiAsync

api = AdCtfApiSync("https://scoreboard.ctf.saarland/api/attack.json")
info = api.attack_info()
api2 = AdCtfApiAsync("https://scoreboard.ctf.saarland/api/attack.json")
info = await api2.attack_info()
```

Optional parameters can be passed to the `configure` function or the API constructors:

- `url: str` (default: `CTF_API` environment variable)
- `tmp_directory: str | Path` (default: `/tmp` or OS-specific alternative)
- `lifetime: float` (default: 30 seconds) - after this time, cached data is invalidated and refreshed
- `timeout: float` (default: 10 seconds) - abort game API requests after this duration
- `decoder: Decoder` (default: generic decoder) - custom decoder, if your game's format is different from what we've
  seen so far
- `aiohttp_arguments: dict` - additional arguments passed to the aiohttp Session which contacts the game API

The `AttackInfo` class itself has these methods:

```python
info: AttackInfo

# Get attackable teams
print(info.teams)  # list of Team objects
print(info.teams[0].id, info.teams[0].ip, info.teams[0].name)  # Team is ID, IP, and optional name
print(info.team("10.32.1.2"))  # query Team object by ID, IP, or name

# set of service names
print(info.services)

# raw flag IDs for a service and team.
# team can be ID, IP, or name. 
# Return data format is determined by game API.
print(info.flag_id_raw("servicename", "10.32.1.2"))
# => {"227": "abc", "228": "def", ...}

# Get flag IDs as string list (independent of game API format, but less precise)
print(info.flag_id_flat("servicename", "10.32.1.2"))
# => ["abc", "def"]
```

Server Documentation
--------------------

```shell
# Simple usage:
python -m attackapi.server --help
```

Options:

- `--port PORT`
- `--url URL`: API url to get CTF info from.
- `--tmp-directory TMP_DIRECTORY`: Cache directory
- `--lifetime LIFETIME`: Lifetime of cached data in seconds
- `--timeout TIMEOUT`: Timeout for API calls in seconds

```shell
# Usage for higher load scenarios:
pip install ctf-attackapi[gunicorn]
gunicorn attackapi.server:create_app --bind :14320 --worker-class attackapi.server.worker.MyGunicornWebWorker --workers 4
```

Environment variables:

- `CTF_API`: URL to get CTF info from.
- `CTF_API_TMP_DIR`: Cache directory (gunicorn only)
- `CTF_API_LIFETIME`: Lifetime of cached data in seconds (gunicorn only)
- `CTF_API_TIMEOUT`: Timeout for API calls in seconds (gunicorn only)

You can also use docker to run the server:
```shell
# edit compose.yaml and insert your CTF API URL before!
docker compose up -d
```


Using attackapi for other information (scoreboard etc.)
-------------------------------------------------------
Feel free to re-use the caching layers for other information, like the current scoreboard.
The class `JsonAdCtfApiAsync` accepts arbitrary JSON endpoints:

```python
from attackapi.async_api import JsonAdCtfApiAsync

info = await JsonAdCtfApiAsync("https://scoreboard.ctf.saarland/api/scoreboard_current.json").retrieve()
```
