This is the multi-page printable view of this section. Click here to print.
Developer Guides
1 - Entensions
How can we extend chall-manager capabilities ? You cannot, in itself: there is no support for live-mutability of functionalities, plugins, nor there will be (immutability is both an operation and security principle, determinism is a requirement).
But as chall-manager is designed as a Micro Service, you only have to reuse it !
Hacking chall-manager API
Taking a few steps back, you can abstract the chall-manager API to fit your needs:
- the
connection_info
is an Output data from the instance to the player. - the
flag
is an optional Output data from the instance to the backend. Then, if you want to pass additional data, you can use those commmunications buses.
Case studies
Follows some extension case studies.
MultiStep & MultiFlags
The original idea comes from the JointCyberRange, the following architecture is our proposal to solve the problem. In the “MultiStep challenge” problem they would like to have Jeopardy-style challenges constructed as a chain of steps, where each step has its own flag. To completly flag the challenge, the player have to get all flags in the proper order. Their target environment is an integration in CTFd as a plugin, and challenges deployed to Kubernetes.
Deploying those instances, isolating them, janitoring if necessary are requirements, thus would have been reimplemented. But chall-manager can deploy scenarios to whatever environment. Our proposal is then to cut the problem in two parts according to the Separation of Concerns Principle:
- a CTFd plugin that implement a new challenge type, and communicate with chall-manager
- chall-manager to deploy the instances
The connection_info
can be unchanged from its native usage in chall-manager.
The flag
output could contain a JSON object describing the flags chain and internal requirements.
Through this architecture, JCR would be able to fit their needs shortly by capitalizing on the chall-manager capabilities, thus extend its goals. Moreover, it would enable them to provide the community a CTFd plugin that does not only fit Kubernetes, thanks to the genericity.
2 - Integrate with a CTF platform
So you want to integrate chall-manager with a CTF platform ? Good job, you are contributing to the CTF ecosystem !
Here are the known integrations in CTF platforms:
The design
The API is split in two services:
- the
ChallengeStore
to handle the CRUD operations on challenges (ids, scenarios, etc.). - the
InstanceManager
to handle players CRUD operations on instances.
You’ll have to handle both services as part of the chall-manager API if you want proper integration.
We encourage you to add additional efforts around this integration, with for instance:
- management views to monitor which challenge is started for every players.
- pre-provisionning to better handle load spikes at the beginning of the event.
- add rate limiting through a mana.
- the support of OpenTelemetry for distributed tracing.
Use the proto
The chall-manager was conceived using a Model-Based Systems Engineering practice, so API models (the contracts) were written, and then the code was generated.
This makes the .proto
files the first-class citizens you may want to use in order to integrate chall-manager to a CTF platform.
Those could be found in the subdirectories here. Refer the your proto-to-code tool for generating a client from those.
If you are using Golang, you can directly use the generated clients for the ChallengeStore
and InstanceManager
services API.
If you cannot or don’t want to use the proto files, you can use the gateway API.
Use the gateway
Because some languages don’t support gRPC, or you don’t want to, you can simply communicate with chall-manager through its JSON REST API.
To access this gateway, you have to start your chall-manager with the proper configuration:
- either
--gw
as an arg orGATEWAY=true
as a varenv - either
--gw-swagger
as an arg orGATEWAY_SWAGGER=true
as a varenv
You can then reach the Swagger at http://my-chall-manager:9090/swagger/#
, which should show you the following.
Use this Swagger to understand the API, and build your language-specific client in order to integrate chall-manager. We do not provide official language-specific REST JSON API clients.