ctf-attackapi 0.1.0__tar.gz

ctf_attackapi-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+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()
+```

ctf_attackapi-0.1.0/README.md

@@ -0,0 +1,197 @@
+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()
+```

ctf_attackapi-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "ctf-attackapi"
+version = "0.1.0"
+description = "Get attack infos in attack-defense CTFs quickly to your exploits. CTF-agnostic and cached."
+readme = "README.md"
+license = "MIT"
+license_files = ["LICENSE.txt"]
+keywords = ["Attack-Defense", "CTF", "Attack API", "Attack Info", "Flag IDs", "FAUST CTF", "ENOWARS", "saarCTF"]
+authors = [
+    { name = "Markus Bauer", email = "markus.bauer@cispa.saarland" }
+]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.13.3",
+    "aiologic>=0.16.0",
+    "filelock>=3.19.1",
+    "pyyaml>=6.0.3",
+    "typing-extensions>=4.15.0",
+]
+
+[project.optional-dependencies]
+server = [
+    "gunicorn>=23.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Attacking-Lab/ctf-attackapi"
+Repository = "https://github.com/Attacking-Lab/ctf-attackapi"
+Issues = "https://github.com/Attacking-Lab/ctf-attackapi/issues"
+Background = "https://wiki.attacking-lab.com/attack-defense/"
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"
+
+[project.scripts]
+ctf-attackapi-server = "attackapi.server:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=8.4.2",
+    "types-pyyaml>=6.0.12.20250915",
+]
+
+[tool.uv.build-backend]
+module-name = "attackapi"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.mypy]
+python_version = "3.9"
+disallow_untyped_defs = true
+packages = ["attackapi", "tests", "examples"]
+mypy_path = ["./src", "./tests", "./examples"]

ctf_attackapi-0.1.0/src/attackapi/__init__.py

@@ -0,0 +1,4 @@
+from .models import Team, AttackInfo
+from .functional import configure, attack_info, attack_info_async
+
+__all__ = ["Team", "AttackInfo", "configure", "attack_info", "attack_info_async"]

ctf_attackapi-0.1.0/src/attackapi/async_api/__init__.py

@@ -0,0 +1,4 @@
+from .api import AdCtfApiAsync, JsonAdCtfApiAsync
+from .decoders import Decoder, Dialect
+
+__all__ = ["AdCtfApiAsync", "JsonAdCtfApiAsync", "Decoder", "Dialect"]