Black Team Agent (BTA)
**********************

The scoring engine exposes an HTTP API for Black Team Agents (BTAs) to
retrieve flags to plant on hosts and to report flags that have been
planted. Although operated by the Black Team, BTAs run on Blue Team
infrastructure. Their check-ins allow the engine to score agent
availability and verify indicators of compromise via Red Team flags.
BTAs periodically "check in" with the engine.

Configuration
=============

Two settings must be configured before BTAs can communicate with the
engine:

``agent_psk``
  Pre-shared key used to derive per-team encryption keys.

``agent_show_flag_early_mins``
  Number of minutes before a flag becomes active that the agent may
  retrieve flag details.

Check-in
========

A BTA performs a POST request to ``/api/agent/checkin`` with the team
name provided in the ``t`` query parameter. The request body must be an
AES-GCM encrypted JSON document with the following structure::

    {
      "team": "<team name>",
      "host": "<hostname or ip>",
      "plat": "win" | "nix",
      "flags": ["<flag id>", ...]
    }

The AES-GCM key is the SHA-256 hash of ``team_name + agent_psk``. A
random 12 byte nonce is prepended to the encrypted payload. The request
should be sent with the ``Content-Type`` header set to
``application/octet-stream``.

The optional ``flags`` list contains the IDs of any flags that have been
successfully planted since the last check-in.

Response
========

The engine responds with an encrypted payload of the same format. After
decryption the payload resembles::

    {
      "flags": [ { ...flag definition... } ],
      "config": { "checkin_interval": { "secs": <seconds>, "nanos": 0 } },
      "timestamp": <unix timestamp>
    }

``flags`` is the list of new flags to plant. Each flag entry includes
fields such as ``id``, ``type``, ``data``, ``platform``, ``start_time``
and ``end_time``. The agent should report the ``id`` of each flag it
plants in the next check-in.

``config.checkin_interval.secs`` tells the agent how long to wait before
contacting the engine again. This value is taken from the
``agent_checkin_interval_sec`` setting. ``timestamp`` is the server's
current time in seconds since the Unix epoch.