ctf-attackapi 0.1.0__py3-none-any.whl

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"]

attackapi/async_api/__init__.py

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

attackapi/async_api/api.py

@@ -0,0 +1,225 @@
+import hashlib
+import os
+import sys
+import tempfile
+import time
+from importlib.metadata import version
+from pathlib import Path
+from typing import Optional, Union, Generic, TypeVar, AsyncContextManager, Any
+
+import aiologic
+from aiohttp import ClientSession, ClientTimeout
+from filelock import FileLock
+
+from attackapi.async_api.decoders import Decoder, GenericDecoder, JSONDecoder
+from attackapi.async_api.filelock import acquire_filelock
+from attackapi.models import AttackInfo
+
+T = TypeVar("T")
+
+
+class GlobalCache(Generic[T]):
+    """In-memory cache for API responses. Shared between threads/loops, not shared between processes."""
+
+    def __init__(self) -> None:
+        # take the lock before modifying the cache.
+        # thanks to GIL this is not necessary for thread safety, but it avoids multiple concurrent loads
+        self.lock = aiologic.Lock()
+        self._cache: dict[str, tuple[float, T]] = {}
+
+    def age(self, key: str) -> Optional[float]:
+        if key in self._cache:
+            return time.time() - self._cache[key][0]
+        return None
+
+    def get(self, key: str) -> T:
+        return self._cache[key][1]
+
+    def set(self, key: str, value: T) -> None:
+        self._cache[key] = (time.time(), value)
+
+
+_api_response_cache: GlobalCache[Any] = GlobalCache()
+
+
+class FileCache:
+    def __init__(self, path: Path, lock: Path) -> None:
+        self._path = path
+        self._lock = lock
+
+    def age(self) -> Optional[float]:
+        try:
+            return time.time() - self._path.stat().st_mtime
+        except FileNotFoundError:
+            return None
+
+    def get(self) -> Optional[bytes]:
+        """
+        On Linux: not necessary to have the lock()
+        On Windows: Must only be called while the lock() is taken
+        """
+        try:
+            return self._path.read_bytes()
+        except FileNotFoundError:
+            pass
+        return None
+
+    def set(self, value: bytes) -> None:
+        """Must only be called while the lock() is taken"""
+        _atomic_write(self._path, value)
+
+    def lock(self) -> AsyncContextManager[None]:
+        return acquire_filelock(FileLock(self._lock))
+
+
+def _atomic_write(p: Path, raw: bytes) -> None:
+    tmpfile = p.with_suffix(f".json.tmp")
+    with tmpfile.open("wb") as f:
+        f.write(raw)
+        f.flush()
+        os.fsync(f.fileno())
+    tmpfile.replace(p)
+
+
+class GenericAdCtfApiAsync(Generic[T]):
+    def __init__(self, decoder: GenericDecoder[T], url: str = "",
+                 tmp_directory: Union[str, Path] = tempfile.gettempdir(), *,
+                 lifetime: float = 30.0, timeout: float = 10.0,
+                 aiohttp_arguments: Optional[dict] = None) -> None:
+        """
+        Create a new API client.
+
+        :param decoder: A decoder for API responses
+        :param url: URL of your game's API
+        :param tmp_directory: where to store cache files
+        :param lifetime: How long to cache data for (in seconds)
+        :param timeout: How long to wait for API calls (in seconds)
+        :param aiohttp_arguments: Optional arguments to pass to aiohttp.ClientSession
+        """
+        if timeout < 1:
+            raise ValueError("Timeout must be at least 1 second")
+        if lifetime < timeout:
+            raise ValueError("Lifetime must be at least as long as timeout")
+
+        self._url = url
+        self._lifetime = lifetime
+        self._timeout = timeout
+        self._decoder = decoder
+        self._aiohttp_arguments = aiohttp_arguments or {
+            "headers": {"User-Agent": "python/attackapi " + version("ctf-attackapi")}
+        }
+        self._cache_key = hashlib.sha256(url.encode()).hexdigest()[:12]
+        self._file_cache = FileCache(
+            Path(tmp_directory) / f"ctf-{self._cache_key}.json",
+            Path(tmp_directory) / f"ctf-{self._cache_key}.json.lock"
+        )
+
+    async def retrieve(self) -> T:
+        """
+        Get the current attack info. Either from cache, from disk, or from game API.
+        This method might fail with aiohttp exceptions.
+        """
+        # Step 1: check in-process cache
+        info = self._check_memory_cache()
+        if info is not None:
+            return info
+        # not found? lock it to avoid concurrent loads
+        async with _api_response_cache.lock:
+            # check again to avoid race conditions
+            info = self._check_memory_cache()
+            if info is not None:
+                return info
+            # not found => load from file or API
+            info = await self._attack_info_from_file()
+            _api_response_cache.set(self._cache_key, info)
+            return info
+
+    def _check_memory_cache(self) -> Optional[T]:
+        if (age := _api_response_cache.age(self._cache_key)) is not None and age <= self._lifetime:
+            return _api_response_cache.get(self._cache_key)
+        return None
+
+    def _check_file_cache(self) -> Optional[T]:
+        if (age := self._file_cache.age()) is not None and age <= self._lifetime:
+            raw = self._file_cache.get()
+            if raw is not None:
+                return self._decoder.parse(raw)
+        return None
+
+    async def _attack_info_from_file(self) -> T:
+        # Step 2: try to load from file
+        # this does not work on Windows, because concurrent read + replacing files is not possible.
+        # for better performance please use Linux
+        if sys.platform != "win32":
+            info = self._check_file_cache()
+            if info is not None:
+                return info
+        # not found? lock it to avoid concurrent API requests
+        async with self._file_cache.lock():
+            # recheck to avoid race conditions
+            info = self._check_file_cache()
+            if info is not None:
+                return info
+            # not found => load from API
+            raw = await self._attack_info_from_remote()
+            info = self._decoder.parse(raw)
+            # and save to file (atomic)
+            self._file_cache.set(raw)
+            return info
+
+    async def _attack_info_from_remote(self) -> bytes:
+        async with ClientSession(**self._aiohttp_arguments) as session:
+            async with session.get(self._url, timeout=ClientTimeout(total=self._timeout)) as response:
+                response.raise_for_status()
+                return await response.read()
+
+
+class JsonAdCtfApiAsync(GenericAdCtfApiAsync[dict]):
+    def __init__(self, url: str, tmp_directory: Union[str, Path] = tempfile.gettempdir(), *,
+                 lifetime: float = 30.0, timeout: float = 10.0,
+                 aiohttp_arguments: Optional[dict] = None) -> None:
+        """
+        Create a new API client.
+
+        :param url: URL of any of your game's APIs
+        :param tmp_directory: where to store cache files
+        :param lifetime: How long to cache data for (in seconds)
+        :param timeout: How long to wait for API calls (in seconds)
+        :param decoder: A custom decoder for API responses, if the default one doesn't work for your game
+        :param aiohttp_arguments: Optional arguments to pass to aiohttp.ClientSession
+        """
+        super().__init__(decoder=JSONDecoder(), url=url, tmp_directory=tmp_directory, lifetime=lifetime,
+                         timeout=timeout, aiohttp_arguments=aiohttp_arguments)
+
+
+class AdCtfApiAsync(GenericAdCtfApiAsync[AttackInfo]):
+    """
+    Async API to retrieve AD team / flag information with as much caching as possible.
+    """
+
+    def __init__(self, url: str = "", tmp_directory: Union[str, Path] = tempfile.gettempdir(), *,
+                 lifetime: float = 30.0, timeout: float = 10.0, decoder: Optional[Decoder] = None,
+                 aiohttp_arguments: Optional[dict] = None) -> None:
+        """
+        Create a new API client.
+
+        :param url: URL of your game's API (defaults to environment variable CTF_API)
+        :param tmp_directory: where to store cache files
+        :param lifetime: How long to cache data for (in seconds)
+        :param timeout: How long to wait for API calls (in seconds)
+        :param decoder: A custom decoder for API responses, if the default one doesn't work for your game
+        :param aiohttp_arguments: Optional arguments to pass to aiohttp.ClientSession
+        """
+        if not url:
+            if "CTF_API" not in os.environ:
+                raise Exception("Please call configure() or set CTF_API environment variable!")
+            url = os.environ["CTF_API"]
+        super().__init__(decoder=decoder or Decoder(), url=url, tmp_directory=tmp_directory, lifetime=lifetime,
+                         timeout=timeout, aiohttp_arguments=aiohttp_arguments)
+
+    async def attack_info(self) -> AttackInfo:
+        """
+        Get the current attack info. Either from cache, from disk, or from game API.
+        This method might fail with aiohttp exceptions.
+        """
+        return await self.retrieve()

attackapi/async_api/decoders.py

@@ -0,0 +1,173 @@
+"""
+Summary of different API formats:
+saarctf: flag_ids => {service_name => {ip => data}}   {tick: a, tick2: [b, c]}
+faust:   flag_ids => {service_name => {ID => data}}   [a, b]
+enowars: services => {service_name => {ip => data}}   {tick: {X: [a], Y: [b]}}
+
+Additional team list:
+saarctf: teams => [0 => {id: ..., name: ..., logo: ...}]
+faust:   teams => [ID1, ID2, ...]
+enowars: availableTeams: [IP1, IP2, ...]
+"""
+import json
+from abc import abstractmethod, ABC
+from dataclasses import dataclass
+from typing import Optional, Generic, TypeVar
+
+from attackapi.models import AttackInfo, Team
+
+
+@dataclass
+class Dialect(ABC):
+    """ID/IP foo for the different games."""
+    name: str
+    ip_pattern: Optional[str] = None  # format string to get IP from ID
+
+    @abstractmethod
+    def matches(self, data: dict) -> bool:
+        raise NotImplementedError
+
+    def id_from_ip(self, ip: str) -> int:
+        return 0
+
+    def ip_from_id(self, team_id: int) -> str:
+        if self.ip_pattern is None:
+            raise Exception(f"ID to IP conversion required, but no IP pattern defined for dialect {self.name!r}")
+        return self.ip_pattern.format(team_id)
+
+
+class DefaultDialect(Dialect):
+    def matches(self, data: dict) -> bool:
+        return True
+
+
+class SaarctfDialect(Dialect):
+    def matches(self, data: dict) -> bool:
+        return "flag_ids" in data and "teams" in data and len(data["teams"]) > 0 and isinstance(data["teams"][0], dict)
+
+    def id_from_ip(self, ip: str) -> int:
+        return int(ip.split(".")[2])  # actually not needed, saarCTF API exposes full team info
+
+    def ip_from_id(self, team_id: int) -> str:
+        return f"10.{32 + (team_id // 200)}.{team_id % 200}.2"  # actually not needed, saarCTF API exposes full team info
+
+
+class FaustDialect(Dialect):
+    def matches(self, data: dict) -> bool:
+        return "flag_ids" in data and "teams" in data and len(data["teams"]) > 0 and isinstance(data["teams"][0], int)
+
+    def id_from_ip(self, ip: str) -> int:
+        return int(ip.split(":")[2])
+
+
+class EnowarsDialect(Dialect):
+    def matches(self, data: dict) -> bool:
+        return "services" in data and "availableTeams" in data
+
+    def id_from_ip(self, ip: str) -> int:
+        """Actually, IDs don't matter for enowars format"""
+        return int(ip.split(".")[2])
+
+
+DIALECTS = [
+    SaarctfDialect("saarctf"),
+    FaustDialect("faustctf", "fd66:666:{:d}::2"),
+    EnowarsDialect("enowars", "10.1.{:d}.1"),
+    DefaultDialect("none")
+]
+
+T = TypeVar("T")
+
+
+class GenericDecoder(ABC, Generic[T]):
+    @abstractmethod
+    def parse(self, raw: bytes) -> T:
+        raise NotImplementedError()
+
+
+class JSONDecoder(GenericDecoder[dict]):
+    def parse(self, raw: bytes) -> dict:
+        return json.loads(raw)
+
+
+class Decoder(GenericDecoder[AttackInfo]):
+    """
+    A decoder converts the game APIs response (in bytes) into teams, services, and attack information.
+    """
+
+    def __init__(self, dialect: Optional[Dialect] = None) -> None:
+        """
+        :param dialect: auto-inferred by default
+        """
+        self._dialect = dialect
+
+    def parse(self, raw: bytes) -> AttackInfo:
+        """
+        Converts game API response to attack infos.
+        :param raw:
+        :raises ValueError: If data is invalid
+        :return:
+        """
+        info = AttackInfo(raw=raw)
+        data = json.loads(raw)
+        dialect = self._get_dialect(data)
+
+        if "flag_ids" in data:
+            self._parse_services(info, data["flag_ids"])
+        elif "services" in data:
+            self._parse_services(info, data["services"])
+        else:
+            raise ValueError("Unknown format - no flag_ids or services key found")
+
+        if "teams" in data:
+            self._parse_teams(dialect, info, data["teams"])
+        elif "availableTeams" in data:
+            self._parse_teams(dialect, info, data["availableTeams"])
+        else:
+            raise ValueError("Unknown format - no teams or availableTeams key found")
+
+        return info
+
+    def _get_dialect(self, data: dict) -> Dialect:
+        if self._dialect is not None:
+            return self._dialect
+        for dialect in DIALECTS:
+            if dialect.matches(data):
+                return dialect
+        return DefaultDialect("none")
+
+    def _parse_services(self, info: AttackInfo, services: dict) -> None:
+        for service_name, flag_ids in services.items():
+            if not isinstance(flag_ids, dict):
+                raise ValueError(f"Invalid flag_ids format for service {service_name!r}: {type(flag_ids)}")
+            info.services.add(service_name)
+            info.flag_ids[service_name.lower()] = flag_ids
+
+    def _parse_teams(self, dialect: Dialect, info: AttackInfo, teams: list) -> None:
+        for team in teams:
+            if isinstance(team, int):
+                team = Team(
+                    id=team,
+                    ip=dialect.ip_from_id(team),
+                    name=f"Team #{team}"
+                )
+            elif isinstance(team, str):
+                team = Team(id=dialect.id_from_ip(team), ip=team, name=team)
+            elif isinstance(team, dict):
+                if not team.get("online", True):
+                    continue
+                team = Team(
+                    id=team["id"],
+                    ip=team["ip"] if "ip" in team else dialect.ip_from_id(team["id"]),
+                    name=team["name"]
+                )
+            else:
+                raise ValueError(f"Unknown team type: {type(team)}: {json.dumps(team)}")
+
+            info.teams.append(team)
+            if team.id is not None:
+                info.team_lookup[str(team.id)] = team
+            if team.ip is not None:
+                info.team_lookup[team.ip.lower()] = team
+            if team.name is not None:
+                info.team_lookup[team.name.lower()] = team

attackapi/async_api/filelock.py

@@ -0,0 +1,30 @@
+import asyncio
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from filelock import BaseFileLock, Timeout
+
+
+@asynccontextmanager
+async def acquire_filelock(fl: BaseFileLock, timeout: float = 10, interval: float = 0.01) -> AsyncGenerator[None, None]:
+    """
+    Acquire filelock, async_api implementation.
+    Adapted from https://github.com/tox-dev/filelock/issues/78#issuecomment-1966513766
+    """
+    for _ in range(int(timeout / interval)):
+        try:
+            fl.acquire(blocking=False)
+        except Timeout:
+            await asyncio.sleep(interval)
+            continue
+        # We want to have the exclusive lock
+        if fl.lock_counter <= 1:
+            try:
+                yield
+            finally:
+                fl.release()
+            return
+        # reentrant hold by an outer acquire: back off and retry
+        fl.release()
+        await asyncio.sleep(interval)
+    raise TimeoutError("Could not obtain file lock")

attackapi/functional.py

@@ -0,0 +1,46 @@
+import tempfile
+from typing import Optional, Any
+
+from attackapi import AttackInfo
+from attackapi.async_api import AdCtfApiAsync
+from attackapi.sync_api import AdCtfApiSync
+
+_sync_api: Optional[AdCtfApiSync] = None
+_async_api: Optional[AdCtfApiAsync] = None
+
+
+def configure(url: str = "", tmp_directory: str = tempfile.gettempdir(), **kwargs: Any) -> None:
+    """
+    Configure the caching API. Only URL is required.
+
+    :param url: URL of your game's API (defaults to environment variable CTF_API)
+    :param tmp_directory: where to store cache files
+    :param lifetime: How long to cache data for (in seconds)
+    :param timeout: How long to wait for API calls (in seconds)
+    :return:
+    """
+    global _sync_api, _async_api
+    _sync_api = AdCtfApiSync(url, tmp_directory, **kwargs)
+    _async_api = AdCtfApiAsync(url, tmp_directory, **kwargs)
+
+
+def attack_info() -> AttackInfo:
+    """
+    Get the current attack info. Either from cache, from disk, or from game API.
+    This method might fail with aiohttp exceptions.
+    """
+    global _sync_api
+    if _sync_api is None:
+        _sync_api = AdCtfApiSync()
+    return _sync_api.attack_info()
+
+
+async def attack_info_async() -> AttackInfo:
+    """
+    Get the current attack info. Either from cache, from disk, or from game API.
+    This method might fail with aiohttp exceptions.
+    """
+    global _async_api
+    if _async_api is None:
+        _async_api = AdCtfApiAsync()
+    return await _async_api.attack_info()

attackapi/models.py

@@ -0,0 +1,134 @@
+from dataclasses import dataclass, field, asdict
+from typing import Optional, Union, Any, cast
+from typing_extensions import TypeAlias
+
+RawFlagIds: TypeAlias = Union[list, dict[str, Union[str, list, dict]]]
+
+
+def _flat(flag_ids: Any) -> list[str]:
+    if isinstance(flag_ids, list):
+        result = []
+        for value in flag_ids:
+            result += _flat(value)
+        return result
+    if isinstance(flag_ids, dict):
+        result = []
+        for value in flag_ids.values():
+            result += _flat(value)
+        return result
+    return [cast(str, flag_ids)]
+
+
+@dataclass(frozen=True)
+class Team:
+    """
+    An attackable team.
+    IP is given for every game, ID is given or inferred for all known CTFs.
+    Name is not present everywhere.
+    """
+    id: int
+    ip: str
+    name: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class AttackInfo:
+    """
+    Container for all attack info parsed from the game API.
+    Use methods team(), flag_id_raw(), and flag_id_flat() to look up data.
+    Fields teams and services can be iterated.
+    """
+
+    teams: list[Team] = field(default_factory=list)
+    team_lookup: dict[str, Team] = field(default_factory=dict)
+    services: set[str] = field(default_factory=set)
+    flag_ids: dict[str, dict[str, RawFlagIds]] = field(default_factory=dict)
+    raw: bytes = b""  # everything, as given by the game API
+
+    def team(self, name: Union[str, int]) -> Optional[Team]:
+        """
+        Find a team.
+
+        :param name: Team ID, IP, or name (as far as supported by the API)
+        :return:
+        """
+        return self.team_lookup.get(str(name).lower())
+
+    def flag_id_raw(self, service: str, team: Union[str, int, Team]) -> Optional[RawFlagIds]:
+        """
+        Find flag IDs for a service and team. Flag IDs are returned in the APIs raw format.
+
+        :param service: Name of a service (case insensitive, see field "services" for a list of valid names)
+        :param team: Team ID, IP, name, or instance (from .team(...))
+        :return:
+        """
+        flag_ids = self.flag_ids.get(service.lower(), {})
+        if isinstance(team, Team):
+            if str(team.id) in flag_ids:
+                return flag_ids[str(team.id)]
+            if team.ip is not None and team.ip.lower() in flag_ids:
+                return flag_ids[team.ip.lower()]
+            if team.name is not None and team.name.lower() in flag_ids:
+                return flag_ids[team.name.lower()]
+            return None
+        elif isinstance(team, str):
+            team = team.lower()
+            if team in flag_ids:
+                return flag_ids.get(team.lower())
+            elif team in self.team_lookup:
+                return self.flag_id_raw(service, self.team_lookup[team])
+            return None
+        elif isinstance(team, int):
+            if str(team) in flag_ids:
+                return flag_ids.get(str(team))
+            elif str(team) in self.team_lookup:
+                return self.flag_id_raw(service, self.team_lookup[str(team)])
+            return None
+
+        raise ValueError(f"Invalid team type: {type(team)}: {team!r}")
+
+    def flag_id_flat(self, service: str, team: Union[str, int, Team]) -> list[str]:
+        """
+        Find flag IDs for a service and team.
+        Flag IDs are returned as a simple string list, containing all attack info for all flag stores.
+
+        :param service: Name of a service (case insensitive, see field "services" for a list of valid names)
+        :param team: Team ID, IP, name, or instance (from .team(...))
+        :return:
+        """
+        flag_ids = self.flag_id_raw(service, team)
+        return _flat(flag_ids) if flag_ids is not None else []
+
+    def attack_info_raw(self, service: str, team: Union[str, int, Team]) -> Optional[RawFlagIds]:
+        """
+        Find attack info for a service and team. Attack info is returned in the APIs raw format.
+
+        This is an alias for flag_id_raw(...).
+
+        :param service: Name of a service (case insensitive, see field "services" for a list of valid names)
+        :param team: Team ID, IP, name, or instance (from .team(...))
+        :return:
+        """
+        return self.flag_id_raw(service, team)
+
+    def attack_info_flat(self, service: str, team: Union[str, int, Team]) -> list[str]:
+        """
+        Find attack info for a service and team.
+        Attack info is returned as a simple string list, containing all attack info for all flag stores.
+
+        This is an alias for flag_id_flat(...).
+
+        :param service: Name of a service (case insensitive, see field "services" for a list of valid names)
+        :param team: Team ID, IP, name, or instance (from .team(...))
+        :return:
+        """
+        return self.flag_id_flat(service, team)
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    def __repr__(self) -> str:
+        return f"AttackInfo(services={self.services!r}, {len(self.teams)} teams)"

attackapi/server/__init__.py

@@ -0,0 +1,2 @@
+from .server import create_app
+from .__main__ import main

attackapi/server/__main__.py

@@ -0,0 +1,29 @@
+import argparse
+import tempfile
+
+from aiohttp import web
+from aiohttp.web_app import Application
+
+from attackapi.async_api import AdCtfApiAsync
+from attackapi.server.server import AttackApiViews
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=14320)
+    parser.add_argument("--url", type=str, default="",
+                        help="API url to get CTF info from.")
+    parser.add_argument("--tmp-directory", type=str, default=tempfile.gettempdir(),
+                        help="Cache directory")
+    parser.add_argument("--lifetime", type=float, default=30.0, help="Lifetime of cached data in seconds")
+    parser.add_argument("--timeout", type=float, default=10.0, help="Timeout for API calls in seconds")
+    args = parser.parse_args()
+
+    api = AdCtfApiAsync(args.url, args.tmp_directory, lifetime=args.lifetime, timeout=args.timeout)
+    app = Application()
+    app.add_routes(AttackApiViews(api).routes())
+    web.run_app(app, port=args.port)
+
+
+if __name__ == '__main__':
+    main()

attackapi/server/docs.py

@@ -0,0 +1,76 @@
+import json
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+
+def openapi_path() -> Path:
+    return Path(__file__).absolute().parent.parent.parent.parent / "api.yaml"
+
+
+@lru_cache(maxsize=1)
+def docs_json() -> dict:
+    return yaml.safe_load(openapi_path().read_text())
+
+
+@lru_cache(maxsize=1)
+def docs_html() -> str:
+    return TEMPLATE % json.dumps(docs_json())
+
+
+# FROM: https://github.com/yousan/swagger-yaml-to-html/blob/master/swagger-yaml-to-html.py
+TEMPLATE = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>AD CTF API Wrapper</title>
+  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
+  <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.43.0/swagger-ui.css" >
+  <style>
+    html
+    {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *,
+    *:before,
+    *:after
+    {
+      box-sizing: inherit;
+    }
+    body {
+      margin:0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.43.0/swagger-ui-bundle.js"> </script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.43.0/swagger-ui-standalone-preset.js"> </script>
+<script>
+window.onload = function() {
+  var spec = %s;
+  // Build a system
+  const ui = SwaggerUIBundle({
+    spec: spec,
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  })
+  window.ui = ui
+}
+</script>
+</body>
+</html>
+""".strip()

attackapi/server/server.py

@@ -0,0 +1,109 @@
+import json
+import os
+import tempfile
+from typing import Any, Callable
+
+from aiohttp import web
+
+from attackapi import AttackInfo
+from attackapi.async_api import AdCtfApiAsync
+from attackapi.server.docs import docs_html, openapi_path
+
+
+class AttackApiViews:
+    def __init__(self, api: AdCtfApiAsync) -> None:
+        self._api = api
+
+    def routes(self) -> list[web.RouteDef]:
+        return [
+            web.get("/", self.docs),
+            web.get("/api.yaml", self.api_spec),
+            web.get("/api/v1/raw", self.get_raw),
+            web.get("/api/v1/services", self.get_services),
+            web.get("/api/v1/teams", self.get_teams),
+            web.get("/api/v1/attack_info/{service}/{team}", self.get_attack_info),
+            web.get("/api/v1/attack_info_raw/{service}/{team}", self.get_attack_info_raw),
+        ]
+
+    async def docs(self, request: web.Request) -> web.Response:
+        docs = docs_html()
+        docs = docs.replace('"http://localhost:14320"', json.dumps("http://" + request.host))
+        try:
+            info = await self._api.attack_info()
+            if len(info.services) > 0:
+                docs = docs.replace('"RCEaaS"', json.dumps(list(info.services)[0]))
+            if len(info.teams) > 0:
+                docs = docs.replace('"10.32.1.2"', json.dumps(info.teams[0].ip))
+                docs = docs.replace('"example": 1', '"example": ' + json.dumps(info.teams[0].id))
+                docs = docs.replace('"NOP"', json.dumps(info.teams[0].name))
+                if len(info.services) > 0:
+                    s = list(info.services)[0]
+                    raw = info.flag_id_raw(s, info.teams[0])
+                    flat = info.flag_id_flat(s, info.teams[0])
+                    if raw:
+                        docs = docs.replace(
+                            json.dumps({"227": "username1", "228": "username2", "229": "username3"}),
+                            json.dumps(raw)
+                        )
+                        docs = docs.replace(
+                            json.dumps(["username1", "username2", "username3"]),
+                            json.dumps(flat)
+                        )
+        except:  # noqa
+            pass
+        return web.Response(text=docs, content_type="text/html")
+
+    async def api_spec(self, request: web.Request) -> web.FileResponse:
+        return web.FileResponse(openapi_path())
+
+    async def get_raw(self, request: web.Request) -> web.Response:
+        info = await self._api.attack_info()
+        return web.Response(body=info.raw, content_type="application/json")
+
+    async def get_teams(self, request: web.Request) -> web.Response:
+        info = await self._api.attack_info()
+        return web.json_response({"teams": [team.to_dict() for team in info.teams]})
+
+    async def get_services(self, request: web.Request) -> web.Response:
+        info = await self._api.attack_info()
+        return web.json_response({"services": list(info.services)})
+
+    async def _attack_info_common(self, request: web.Request,
+                                  cb: Callable[[AttackInfo, str, str], Any]) -> web.Response:
+        service = request.match_info["service"]
+        team = request.match_info["team"]
+        if not service or not team:
+            raise web.HTTPBadRequest(reason="Invalid team or service")
+        info = await self._api.attack_info()
+        if service.lower() not in info.flag_ids:
+            raise web.HTTPBadRequest(reason=f"Unknown service, or service has no attack info: {service}")
+        flag_ids = cb(info, service, team)
+        return web.json_response(
+            {"attack_info": flag_ids}
+        )
+
+    async def get_attack_info(self, request: web.Request) -> web.Response:
+        def _cb(info: AttackInfo, service: str, team: str) -> Any:
+            return info.flag_id_flat(service, team)
+
+        return await self._attack_info_common(request, _cb)
+
+    async def get_attack_info_raw(self, request: web.Request) -> web.Response:
+        def _cb(info: AttackInfo, service: str, team: str) -> Any:
+            return info.flag_id_raw(service, team)
+
+        return await self._attack_info_common(request, _cb)
+
+
+async def create_app() -> web.Application:
+    """Create the app for gunicorn"""
+    api = AdCtfApiAsync(
+        url=os.environ["CTF_API"],
+        tmp_directory=os.environ.get("CTF_API_TMP_DIR", tempfile.gettempdir()),
+        lifetime=float(os.environ.get("CTF_API_LIFETIME", 30.0)),
+        timeout=float(os.environ.get("CTF_API_TIMEOUT", 10.0))
+    )
+    views = AttackApiViews(api)
+    app = web.Application()
+    app.add_routes(views.routes())
+    return app

attackapi/server/worker.py

@@ -0,0 +1,19 @@
+import asyncio
+
+from aiohttp import GunicornWebWorker
+from gunicorn.workers import base  # type: ignore
+
+
+class MyGunicornWebWorker(GunicornWebWorker):
+    """
+    Hot-patches an issue in aiohttp.
+    https://github.com/aio-libs/aiohttp/issues/11701
+    """
+
+    def init_process(self) -> None:
+        try:
+            super().init_process()
+        except RuntimeError:
+            self.loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self.loop)
+            base.Worker.init_process(self)

attackapi/sync_api.py

@@ -0,0 +1,29 @@
+import asyncio
+import tempfile
+from pathlib import Path
+from typing import Any, Union
+
+from attackapi import AttackInfo
+from attackapi.async_api import AdCtfApiAsync
+
+
+class AdCtfApiSync:
+    def __init__(self, url: str = "", tmp_directory: Union[str, Path] = tempfile.gettempdir(), **kwargs: Any) -> None:
+        """
+        Create a new API client for synchronous use.
+
+        :param url: URL of your game's API (defaults to environment variable CTF_API)
+        :param tmp_directory: where to store cache files
+        :param lifetime: How long to cache data for (in seconds)
+        :param timeout: How long to wait for API calls (in seconds)
+        :param decoder: A custom decoder for API responses, if the default one doesn't work for your game
+        :param aiohttp_arguments: Optional arguments to pass to aiohttp.ClientSession
+        """
+        self._api = AdCtfApiAsync(url, tmp_directory, **kwargs)
+
+    def attack_info(self) -> AttackInfo:
+        """
+        Get the current attack info. Either from cache, from disk, or from game API.
+        This method might fail with aiohttp exceptions.
+        """
+        return asyncio.run(self._api.attack_info())

ctf_attackapi-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+attackapi/__init__.py,sha256=7EtXsvf8MzdEn4U41fXqx3IvMY6dhs-4_yno6onmZW4,186
+attackapi/async_api/__init__.py,sha256=2Mj1sMy57zzieoI4fNq1vvphi_Oj8u1TMy2uN4xD5v0,161
+attackapi/async_api/api.py,sha256=YbhICNMr_T4WWehEZ940wwRrIbqxWhT7YBm3NLw1EDE,8867
+attackapi/async_api/decoders.py,sha256=EOas8JexiyZTmAu9k2MVjabXFtdHZLioAsqUNhZZ0l4,5832
+attackapi/async_api/filelock.py,sha256=mG7agPkkQjpExJNYASigfrVCuiRmAoKGkiZv6bU2vU0,978
+attackapi/functional.py,sha256=9oqgL8XiEt1_k2hFi6yUEo00uf_A9TEJV5HVwiD3AhM,1478
+attackapi/models.py,sha256=4dG_yKGQwY7ny2VR6wSP4AHEyBAP8U3N8P9iP6QxbiY,4983
+attackapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+attackapi/server/__init__.py,sha256=_1uqd49SZm0KlW_jsxHBguKfA9TZdaazTzhP47rMS6Q,58
+attackapi/server/__main__.py,sha256=0B7lIdoRt86KugnmxY5ZABG1hnTRPM9Cc8K5Fy0c2co,1057
+attackapi/server/docs.py,sha256=9EKawP0PYQKbqd-gAZlEXqX3Z3QUcLXB1E0JZGxe9Yo,1810
+attackapi/server/server.py,sha256=8JNIURfjlylq_a1p4xkyrPSlig3SQ7p65pSOtvntGtY,4613
+attackapi/server/worker.py,sha256=z6_QS4vaJYK2fDC35Q4W6eSmBiYr4au8Oabpb0iLvFM,510
+attackapi/sync_api.py,sha256=ws8pkgzeVkj5lJGGoqLuwO5vm7cQYXj3sRsa1MEsStc,1176
+ctf_attackapi-0.1.0.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+ctf_attackapi-0.1.0.dist-info/entry_points.txt,sha256=HOPX0b5DyTBBgRDZINsNdoeYLyHxoH798Mi9VDMzuyQ,64
+ctf_attackapi-0.1.0.dist-info/METADATA,sha256=V2OZ2LQGdZwbfP2yFMhBb_dWNyH2K2y6JLvmVQ44mCY,8691
+ctf_attackapi-0.1.0.dist-info/RECORD,,

ctf_attackapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.27
+Root-Is-Purelib: true
+Tag: py3-none-any

ctf_attackapi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ctf-attackapi-server = attackapi.server:main
+