Tools Service API
Gateway paths: https://<host>/api/v1/tools... (proxied to the service’s
/api/tools...) and https://<host>/api/v1/tasks... (proxied to the
service’s /api/tasks...)
Authentication: through the gateway only, with a JWT bearer token or an
API key sent as X-API-Key
Host names, IDs and keys in the examples are placeholders.
Overview
The tools service runs the security tools found under
open-security-tools/app/tools (52 on 2 October 2026). Each tool is a
plugin with a name, metadata, an input schema and an output schema; the
service discovers them at startup and exposes one run endpoint per tool. The
catalog is whatever GET /api/v1/tools returns on your deployment: this
page does not list the tools.
A tool runs in one of two ways:
- Synchronously:
POST /api/v1/tools/{tool_name}answers with the tool’s output. - Asynchronously:
POST /api/v1/tools/{tool_name}/asyncqueues the run and answers with a task ID that its submitter reads, cancels and lists under/api/v1/tasks.
TLS Certificate Verification
Tools that connect over HTTPS verify the certificate chain and the host name.
When verification fails, the scan returns success: false with the reason
(for example self-signed certificate) and sends no further request; it does
not retry without verification. Tool inputs built on the shared input schema
accept verify_ssl (default true). Setting it to false lets that one scan
read content from whoever answers the connection, including an interceptor,
so its results can no longer be trusted.
ssl_analyzer, ca_analyzer and pki_certificate_manager exist to inspect
certificates, including broken ones: they read the certificate over an
unverified handshake, also attempt a verified one, and report an untrusted
certificate as a finding.
Network Target Policy
Before a tool runs, the service checks where it would connect
(enforce_target_policy in open-security-tools/app/target_policy.py). It
runs the URL guard on every URL in the input, then checks the host, address
and range fields of the network tools: port_scanner,
network_port_scanner, network_vulnerability_scanner, network_scanner,
iot_security_scanner, ssl_analyzer, ca_analyzer,
pki_certificate_manager, database_security_analyzer, dns_enumerator
(its dns_servers, and the name servers it attempts a zone transfer from)
and the registry of a container_security_scanner image. Unless the
operator allows them, it refuses:
- addresses that are private, loopback, link-local, unspecified, multicast,
reserved, shared (
100.64.0.0/10) or otherwise not globally reachable, such as the documentation ranges, and IPv4 addresses embedded in IPv6 ones (IPv4-mapped, 6to4, NAT64); - a CIDR or address range that contains such an address, and any range of
more than 1,024 addresses (an IPv4
/22), checked before the range is expanded; - a host name that resolves to such an address (every answer is checked) or does not resolve; both answer with the same message;
- the deployment’s own names: every name without a dot (
wildbox-redis,postgres,gateway),localhost, names ending in.localhost,.local,.internal,.localdomainor.home.arpa, and the cloud metadata names; - spellings that are not canonical (
127.1), values with whitespace or control characters, and an address or a range written with an IPv6 zone id (fe80::1%eth0).
How a refusal reaches the caller depends on the path: the synchronous run
and the asynchronous submission answer 400 with the reason in
error.message and the field that held the target in
error.details.errors, and the submission creates no task; a task whose
target is refused only when it runs (the name resolves to another address by
then) ends with status failed and the reason in error; and a
security_automation_orchestrator step that names a refused target fails.
Every failed step of a security_automation_orchestrator workflow has an
error_code beside its error_message
(#755):
error_code |
The step failed because |
|---|---|
tool_not_available |
its tool is not one the orchestrator runs, or could not be loaded |
step_refused |
the target policy refuses its target, or the tool acts for a caller and must be called through the API |
invalid_parameters |
the tool’s schema refuses its parameters; error_message names each field and why |
tool_rejected_input |
the tool raised an error while it ran on its parameters |
service_unavailable |
a service the tool needs could not be reached |
internal_error |
of a fault in the service |
step_failed |
of anything else |
For the last four error_message is one fixed sentence per code. What was
raised is in the service’s log, by class and line, and is never part of the
workflow’s result.
The reason says what kind of refusal it is and, for an internal target,
names the policy and the setting that governs it, for example
The target is a private, loopback, link-local, multicast, reserved or otherwise internal address (network target policy; operators can allow internal targets with TOOLS_ALLOWED_INTERNAL_TARGETS).
It does not repeat the target, which it quoted until
#774. The field is
named instead, as in a 422:
{
"error": {
"code": 400,
"message": "The target is a private, loopback, link-local, multicast, reserved or otherwise internal address (network target policy; operators can allow internal targets with TOOLS_ALLOWED_INTERNAL_TARGETS)",
"details": {
"reason": "The target is a private, loopback, link-local, multicast, reserved or otherwise internal address (network target policy; operators can allow internal targets with TOOLS_ALLOWED_INTERNAL_TARGETS)",
"errors": [
{"loc": ["target"], "msg": "The target is a private, loopback, link-local, multicast, reserved or otherwise internal address (network target policy; operators can allow internal targets with TOOLS_ALLOWED_INTERNAL_TARGETS)", "type": "target_internal"}
]
}
}
}
type is target_internal (an internal address, a range with one in it, a
name of the deployment, a name that does not resolve or resolves inside),
target_too_large (a range of more than 1,024 addresses),
target_invalid (not a host, an address or a range) or url_refused (a
URL the URL guard refuses; loc is the field of the input the URL is
under). The result of a task and the error of a workflow step, which are
one string, end with the field and the type in brackets:
... (target: target_internal).
TOOLS_ALLOWED_INTERNAL_TARGETS (empty by default) opens internal targets
for every caller of every network tool. It is a comma-separated list of
CIDR ranges with their host bits zero, IP addresses and host names, for
example 10.20.0.0/16,192.168.50.0/24,lab-dc01. An address is allowed
inside a listed range; a range when all its internal addresses are inside
listed ranges; a host name when it is listed exactly (no subdomains) or
when all its internal addresses are inside listed ranges. Set it in .env:
docker-compose.yml passes it to both the api service and the
tools-worker, which checks asynchronous runs. An entry that is not a
CIDR range, an IP address or a host name stops both at startup. The range
limit of 1,024 addresses per input still applies to allowed ranges.
The check resolves a name, and most tools resolve it again when they connect: a name whose DNS answer changes between the two lookups can still reach an internal address in that window.
network_scanner takes network as an IP address, a CIDR range or a
last-octet range written a.b.c.10-20, at most 1,024 addresses; it
refuses a larger range before any probe. It pings each host (scan_type
ping, the default) and, with scan_type tcp, also tries a TCP connect
to common ports on the hosts that answer. timeout (seconds per probe,
1 to 30, default 3) and max_threads (concurrent probes, 1 to 100,
default 50) bound the scan.
Table of Contents
- Authentication
- Endpoint Summary
- Tool Catalog
- Tool Execution
- Asynchronous Tasks
- Health and Internal Endpoints
- Rate Limits
- Errors
- Examples
Authentication
Every request goes through the gateway. The gateway validates the
credential with the identity service, then forwards the caller to the tools
service as X-Wildbox-User-ID, X-Wildbox-Team-ID and X-Wildbox-Role
headers, together with the X-Gateway-Secret proof of origin. The service
answers 401 to a request that does not carry those headers, so its own port
is not an entry point. Its API_KEY setting is not a credential: the direct
X-API-Key path was removed in #565.
Get a token with the gateway login route:
CA=open-security-gateway/ssl/wildbox.crt
TOKEN=$(curl -s --cacert "$CA" -X POST https://<host>/auth/jwt/login \
--data-urlencode "username=$ADMIN_EMAIL" \
--data-urlencode "password=$ADMIN_PASSWORD" | jq -r .access_token)
curl -s --cacert "$CA" https://<host>/api/v1/tools \
-H "Authorization: Bearer $TOKEN"
Or create an API key (POST /api/v1/identity/api-keys, or
POST /api/v1/identity/teams/{team_id}/api-keys for a team key) and send
it as X-API-Key: <key>. The
Authentication and sessions guide covers
both credentials.
A JWT is not limited by scopes. An API key with scopes needs the following
ones, which the gateway checks before the request reaches the service. The
service checks tools:execute again, on the scopes the gateway forwards,
on the routes that run a tool or cancel a task:
| Request | Required scope |
|---|---|
GET /api/v1/tools, GET /api/v1/tools/{tool_name}/info |
tools:read |
POST /api/v1/tools/{tool_name}, POST /api/v1/tools/{tool_name}/async |
tools:execute |
GET /api/v1/tasks, GET /api/v1/tasks/{task_id} |
tools:read |
DELETE /api/v1/tasks/{task_id} |
tools:execute |
tools:execute and the generic read and write scopes also satisfy
tools:read, and write satisfies tools:execute. A key missing the scope
gets 403 insufficient_scope, and the body names the required_scope.
Endpoint Summary
| Method | Gateway path | Purpose |
|---|---|---|
GET |
/api/v1/tools |
List the tools |
GET |
/api/v1/tools/{tool_name}/info |
Metadata and JSON schemas of one tool |
POST |
/api/v1/tools/{tool_name} |
Run a tool and wait for its output |
POST |
/api/v1/tools/{tool_name}/async |
Queue a run, get a task ID |
GET |
/api/v1/tasks |
The caller’s tasks of the last day |
GET |
/api/v1/tasks/{task_id} |
Status and result of one task |
DELETE |
/api/v1/tasks/{task_id} |
Cancel a pending or running task |
The gateway answers any other /api/... path with
404 {"error":"endpoint_not_found", ...}, and /tools/ (the removed
standalone tools UI) with 404 as well.
Tool Catalog
GET /api/v1/tools
The tools this deployment loaded. No query parameters, no pagination.
curl -s --cacert "$CA" https://<host>/api/v1/tools \
-H "Authorization: Bearer $TOKEN"
Response (200 OK): a JSON array, one object per tool.
[
{
"name": "hash_generator",
"display_name": "Hash Generator",
"description": "Generate and analyze various cryptographic hashes with security recommendations",
"version": "1.0.0",
"author": "Wildbox Security",
"category": "cryptography",
"endpoint": "/api/tools/hash_generator"
}
]
| Field | Description |
|---|---|
name |
Tool name, the {tool_name} of every other route |
display_name |
From the tool’s metadata; the name in title case when the tool sets none |
description |
From the tool’s metadata; No description available when absent |
version, author |
From the tool’s metadata; unknown when absent |
category |
From the tool’s metadata; general when absent |
endpoint |
The run path on the service (/api/tools/{name}). Through the gateway the same tool runs at /api/v1/tools/{name} |
GET /api/v1/tools/{tool_name}/info
The tool’s metadata and the JSON Schema of its input and output. A client
builds the request body from input_schema.
curl -s --cacert "$CA" https://<host>/api/v1/tools/hash_generator/info \
-H "Authorization: Bearer $TOKEN"
Response (200 OK):
{
"name": "hash_generator",
"display_name": "Hash Generator",
"description": "Generate and analyze various cryptographic hashes with security recommendations",
"version": "1.0.0",
"author": "Wildbox Security",
"category": "cryptography",
"endpoint": "/api/tools/hash_generator",
"input_schema": {"title": "HashGeneratorInput", "type": "object", "properties": {"...": "..."}},
"output_schema": {"title": "HashGeneratorOutput", "type": "object", "properties": {"...": "..."}}
}
The metadata keys are the tool’s own TOOL_INFO entries, so they vary from
tool to tool; entries that are classes or functions are left out. name,
endpoint, input_schema and output_schema are always present.
input_schema and output_schema are the Pydantic JSON Schemas of the
models the run endpoint validates with and answers with; either is null
when the tool has no such model.
404 when no tool has that name.
Tool Execution
POST /api/v1/tools/{tool_name}
Run a tool and wait for its output. The request body is a JSON object
matching the tool’s input_schema.
curl -s --cacert "$CA" -X POST https://<host>/api/v1/tools/hash_generator \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"input_text": "wildbox", "hash_types": ["sha256"]}'
Response (200 OK): an object of the tool’s output schema. The service
sets tool_name and execution_time (seconds) on it. Most tools’ outputs
also carry success; a tool that ran but could not do its job (for example
a TLS verification failure) answers 200 with success: false and the reason.
The service refuses a run with these statuses:
| Status | When | error.message |
|---|---|---|
| 400 | A URL or a network target in the input is refused (see Network Target Policy) | The kind of refusal; error.details.errors names the field. The target is not echoed back |
| 404 | No tool has that name | Not Found |
| 403 | The tool acts on behalf of the caller and the caller is not authorized for it (today sql_injection_scanner, which also needs an authenticated caller) |
The authorization reason |
| 403 | The credential the gateway forwarded is an API key without tools:execute, or the request does not state its auth type (a gateway older than the service) |
This API key is not authorized for this operation. with error.details.code INSUFFICIENT_SCOPE; or error.details.code GATEWAY_AUTH_TYPE_REQUIRED |
| 408 | The run exceeded its time limit | Tool execution timed out |
| 422 | The body is not a JSON object | Request validation failed |
| 422 | The body does not match the input schema | Input validation failed; error.details.errors lists loc, msg and type for each field. Submitted values are not echoed back |
| 500 | The tool failed | Tool execution failed, or An internal error occurred (type InternalServerError) for an error the service does not expect from a tool |
| 503 | The tool acts on behalf of the caller and the caller’s hourly allowance cannot be counted, because Redis does not answer (see Rate Limits). The tool was not run | Rate limiting temporarily unavailable |
The time limit is the input’s timeout field when the tool’s schema has
one (the shared input schema defaults it to 30 seconds, 300 at most),
otherwise the service’s TOOL_TIMEOUT (default 300 seconds). The gateway,
however, waits 60 seconds for the service to answer
(proxy_read_timeout in open-security-gateway/nginx/includes/proxy_params.conf):
a run that takes longer gets a 504 from the gateway while the tool keeps
running. Use the asynchronous endpoint for anything that can take a minute.
Asynchronous Tasks
POST /api/v1/tools/{tool_name}/async
Queue a run and return at once. The body is the same tool input as for the synchronous endpoint.
curl -s --cacert "$CA" -X POST https://<host>/api/v1/tools/hash_generator/async \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"input_text": "wildbox", "hash_types": ["sha256"]}'
Response (202 Accepted):
{
"task_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
"status": "accepted",
"tool_name": "hash_generator",
"status_url": "/api/v1/tasks/1b4e28ba-2fa1-41d2-883f-0016d3cca427",
"message": "Task submitted successfully. Use task_id to check status."
}
The submission is checked as a synchronous run is, by the same code, and
nothing that fails the check is queued: 404 (Tool not found) for a
name that is no tool, 422 for an input the tool’s schema refuses, with
the same field errors, and 400 for a target the
network target policy refuses
(#743). No task is
created for any of the three.
The worker checks again when the task runs, because the answer can have
changed: a host name may resolve to another address by then. A task refused
at that point reads status failed with the reason in error: for a
target, the kind of refusal and the field that held the target, never the
target; for an input the tool’s schema refuses, the fields that failed,
never their values. Whether the caller may run
a tool that acts for them is decided when the task runs: a task the tool
refuses reads status refused.
A task whose tool raised an error while it ran reads status failed with
error set to Tool execution failed (<class of the error>), for example
Tool execution failed (ValueError): what the synchronous route says for
the same failure, with the class. The text of the error is neither stored
with the task nor logged, because a tool’s error can repeat the input it was
raised over
(#755).
This holds for an error of any class, and the tool is called once: a task is
not retried for what its tool raised. Until
#774 an error that
was not a ValueError, KeyError, TypeError, ConnectionError or
TimeoutError made the worker call the tool twice more, and the task then
read failed in state FAILURE. Only a task that fails before its tool is
called (Redis does not answer, a fault in the checks) is retried, and reads
retrying meanwhile.
The service records who submitted the task before queuing it. It answers
503 (Asynchronous execution is unavailable) when it cannot record the
owner or queue the task (Redis or the task queue unreachable).
A queued run is stopped after 9 minutes (Celery soft limit 540 seconds,
hard limit 600 seconds in open-security-tools/app/celery_app.py) and then
reports status timeout.
A task whose worker process dies while it runs (killed for memory, a crash
in native code) is put back on the queue and started again. That happens at
most three times: when three starts of a task have ended with the process
gone, the next delivery ends it with status failed and the error
The worker process running this task was lost 3 times; the task was not
started again
(#743). Such a task
used to come back without end.
When the whole worker is killed while it runs a task (docker kill, the
kernel’s out-of-memory killer on the container, a host that goes down), the
task is neither finished nor back in the queue: the broker keeps it for the
worker that took it, and it goes on reading running. A running worker
returns it to the queue once it was taken longer ago than the visibility
timeout, 3600 seconds (broker_transport_options in
open-security-tools/app/celery_app.py), and it looks for such tasks when
it starts and every hundred seconds after that. So the task starts again
from one hour to one hour and a hundred seconds after it was first taken,
if a worker is running then; that start counts as one of the three above.
Task Visibility
A task belongs to the user who submitted it. Only that user can read, cancel or list it. For anyone else, a teammate or an administrator included, it does not exist: reading or canceling it answers 404, the same answer as for an unknown task ID, so the response does not confirm that a task exists, and it is not in their list. A task without an owner record, such as one submitted before owners were recorded, is not readable.
Owner records expire after a day; a task’s result is kept for an hour after
the task finishes (result_expires=3600). The task endpoints have their
own prefix, /api/v1/tasks, because under /api/v1/tools/ the segment
after the prefix is a tool name.
GET /api/v1/tasks/{task_id}
Status, and result once finished, of one of the caller’s tasks.
curl -s --cacert "$CA" https://<host>/api/v1/tasks/1b4e28ba-2fa1-41d2-883f-0016d3cca427 \
-H "Authorization: Bearer $TOKEN"
Response (200 OK), waiting:
{
"task_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
"state": "PENDING",
"tool_name": "hash_generator",
"submitted_at": 1790000000.0,
"status": "pending",
"message": "Task is waiting to be executed"
}
Response (200 OK), finished:
{
"task_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
"state": "SUCCESS",
"tool_name": "hash_generator",
"submitted_at": 1790000000.0,
"status": "completed",
"error": null,
"result": {"success": true, "hash_results": ["..."], "tool_name": "hash_generator", "execution_time": 0.012, "task_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427"},
"duration": 0.012,
"completed_at": "2026-10-03T10:00:01.234567"
}
state is the Celery state. status is what a client acts on:
state |
status |
Other fields |
|---|---|---|
PENDING |
pending |
message |
STARTED or RUNNING |
running |
message; info with the progress fields tool_name, started_at and status when the worker has written them |
SUCCESS |
completed, failed, timeout or refused (the task finished and reports how the tool ended) |
error, result (the tool’s output when completed), duration, completed_at |
FAILURE |
failed (the task failed before its tool was called, after its retries, or was killed at the hard time limit) |
error (Task execution failed (<exception class>), never the exception message), message, completed_at |
RETRY |
retrying |
message, info (the same failure text as error above) |
REVOKED |
cancelled |
message (Task was cancelled), completed_at (null until a worker has dropped or stopped the task: the state is reported as soon as the owner cancels) |
Any other state, including a result record the service cannot read, answers
200 with status unknown and message The task state cannot be read
(state is UNKNOWN when the record is unreadable). The service reads the
task’s record once per request (open-security-tools/app/api/async_router.py),
so a task canceled while it is being read answers with one of these states,
not with a 500.
404 for a task the caller did not submit or that does not exist;
503 (Asynchronous execution is unavailable) when the result backend
(Redis) cannot be reached.
DELETE /api/v1/tasks/{task_id}
Cancel one of the caller’s pending, running or retrying tasks.
curl -s --cacert "$CA" -X DELETE https://<host>/api/v1/tasks/1b4e28ba-2fa1-41d2-883f-0016d3cca427 \
-H "Authorization: Bearer $TOKEN"
Response (200 OK):
{
"task_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
"status": "cancelled",
"message": "Task cancellation requested"
}
The cancellation is recorded with the task before the workers are told
(#743). From then on
the task reads status cancelled, and a task that has not started never
starts: the worker that takes it reads the record first and drops it,
including a worker that was not running when the task was canceled. A task
that is running is stopped (SIGTERM to its process). If it finishes on its
own before that reaches it, it reads the status it finished with.
400 (Task cannot be cancelled (current state: ...)) for a task that
has finished or was already canceled; 404 for a task the caller did not
submit or that does not exist; 503 when Redis cannot be reached.
GET /api/v1/tasks
The caller’s tasks of the last day, newest first.
| Query parameter | Type | Description |
|---|---|---|
limit |
integer | 1 to 100 (default 50) |
curl -s --cacert "$CA" "https://<host>/api/v1/tasks?limit=20" \
-H "Authorization: Bearer $TOKEN"
Response (200 OK):
{
"tasks": [
{
"task_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
"tool_name": "hash_generator",
"submitted_at": 1790000000.0,
"state": "SUCCESS",
"status": "completed",
"status_url": "/api/v1/tasks/1b4e28ba-2fa1-41d2-883f-0016d3cca427"
}
],
"count": 1
}
Health and Internal Endpoints
These endpoints exist only on the tools service itself. The gateway does
not route them (/api/v1/tools/health reaches /api/tools/health on the
service, the run path of a tool named health, not this endpoint), and the
service does not authenticate them. In the default
docker-compose.yml the service port is published on 127.0.0.1:8000
only, so they are reachable from the Docker host and the internal network,
for health probes and operators.
GET /health
curl -s http://127.0.0.1:8000/health
Response (200 OK):
{
"status": "healthy",
"service": "tools",
"version": "0.1.6",
"timestamp": 1790000000.0,
"tools_count": 52,
"active_executions": 0
}
status is degraded (with error, and without the two counts) when the
service cannot read its execution state. version is the service’s one
version, the same the X-API-Version response header and the OpenAPI
schema carry. tools_count is the number of tools loaded and
active_executions the synchronous runs in progress.
The answer names neither the environment, nor the concurrency and timeout
settings, nor the tools: the route answers anyone who reaches the service
port, and a health check needs the status
(#721). The gateway’s
own https://<host>/health reports on the gateway, not on this service.
Other Internal Endpoints
| Path | Content |
|---|---|
/metrics |
Prometheus exposition format: request counts and durations by route (wildbox_http_requests_total, wildbox_http_request_duration_seconds), synchronous tool executions by tool and outcome (wildbox_tool_executions_total) and the asynchronous run metrics. monitoring/prometheus.yml scrapes it |
/openapi.json |
The service’s OpenAPI document, only when ENVIRONMENT is development |
/api |
Service name, version and the path of the tool list (/api/tools, which asks for the gateway’s identity) |
None of them is part of the public API, and /health and these three are
the only routes that answer without the gateway’s identity: every other
route under /api/ answers 401 to a request that does not carry it.
Asynchronous Run Metrics
An asynchronous run executes in tools-worker, which Prometheus does not
scrape. The worker counts in Redis how each task ended, and /metrics of
this service reads the counts on every scrape:
| Metric | Type | What it is |
|---|---|---|
wildbox_tool_async_executions_total{tool, outcome} |
counter | Tasks by tool and outcome, one count per task, made when the task ends |
wildbox_tool_async_queue_length |
gauge | Tasks in the queue that no worker has taken |
wildbox_tool_async_tasks_consumed_total |
counter | Times a worker took a task off the queue: every start (a retried task starts again) and every task it dropped because it was canceled while it waited |
wildbox_tool_async_metrics_up |
gauge | 1 when the three above could be read from Redis; 0, and no value for them, when not |
outcome is one of:
| Outcome | The task |
|---|---|
completed |
ran its tool, which returned (a result with success: false included) |
failed |
ran its tool, which raised; or failed in the worker before its tool was called, after its retries; or was given up after its worker process died three times while running it |
timeout |
was stopped at the soft time limit (9 minutes) or killed at the hard one (10 minutes) |
cancelled |
was canceled with DELETE /api/v1/tasks/{task_id}, while it waited or while it ran |
refused |
ended before its tool was started: the caller may not run the tool, or what the submission accepted is refused when the task runs (the target now resolves to an address that is not allowed, the worker does not have the tool) |
The status a client reads from GET /api/v1/tasks/{task_id} is unchanged
and differs in two places: a task the worker’s own check refused when
it ran (see the submission) reads
failed there, and one killed at the hard time limit reads failed
(Task execution failed (TimeLimitExceeded)). A tool name that is not a
tool is counted under tool="unknown".
The counters are kept in Redis (wildbox:tools:async-outcomes,
wildbox:tools:async-consumed), so they survive a restart of the API and
of the worker and are reset only with the Redis data. A count the worker
cannot write, because Redis does not answer it, is lost: the counters can
be short, never long.
The service has no /api/system/ routes. info, metrics,
operational-metrics and health-aggregate existed there, without
authentication, until they were removed
(#646); a request
for one of them answers 404. What they reported is available elsewhere:
| Was in | Now |
|---|---|
info: tool names |
GET /api/v1/tools, through the gateway |
info: environment, concurrency and timeout settings |
Not served: they are the deployment’s own settings (ENVIRONMENT, MAX_CONCURRENT_TOOLS, TOOL_TIMEOUT), and no route that answers without authentication reports them |
metrics, operational-metrics: counters of synchronous executions (which stayed at zero) |
wildbox_tool_executions_total in /metrics |
health-aggregate: the health of the other services (it reported a healthy stack as degraded) |
Each service’s own health check (docker compose ps), and the up series Prometheus records for every service it scrapes |
Rate Limits
The gateway applies two limits to tools and task requests:
- Per team:
RATE_LIMIT_PER_HOURrequests per hour (default 10000), enforced in fixed 60-second windows of one sixtieth of it, rounded down and at least 1: 166 requests per team with the default (open-security-gateway/nginx/lua/auth_handler.lua). Every authenticated response carriesX-RateLimit-Limit(the per-minute figure),X-RateLimit-RemainingandX-RateLimit-Reset, which describe the current minute, andX-RateLimit-Policy: <per hour>;w=3600. Past the limit the gateway answers 429 withRetry-Afterand{"error": "rate_limit_exceeded", "message": "Rate limit exceeded", "limit_per_hour": 10000, "retry_after_seconds": ...}.RATE_LIMIT_PER_HOURis set in.envand passed to the gateway bydocker-compose.yml; it must be a whole number from 1 to 1,000,000,000, and any other value stops the gateway at startup. - Per client IP: the server-wide nginx
limit_reqzoneglobal, 100 requests per second with a burst of 10, answered with 429. The rate is the gateway’sGATEWAY_RATE_LIMIT_PER_SECONDsetting, 100 unless the operator changed it.
The tools service applies no request rate limit of its own: every request
reaches it through the gateway, already counted against the caller’s team.
RATE_LIMIT_REQUESTS and RATE_LIMIT_WINDOW, which the service read and
never enforced, no longer exist
(#646); setting them
in .env has no effect. What the service does limit is the cost of a call:
MAX_CONCURRENT_TOOLS synchronous runs at a time (10), TOOL_TIMEOUT
seconds per run (300), and, for the tools that act for a caller, a number
of runs per caller in any hour (one for a destructive test). That count is
kept in the service’s Redis, shared by the API and the workers and kept
across restarts; past it the run is refused with 403
(Rate limit exceeded for destructive_test operations), and when Redis
cannot be reached the run is refused with 503
(Rate limiting temporarily unavailable) instead of being let through
uncounted.
Errors
The gateway answers its own refusals with
{"error": "<code>", "message": "..."}:
| Status | error |
Cause |
|---|---|---|
| 400 | invalid_token |
Token longer than 4096 characters |
| 401 | authentication_required |
No bearer token and no X-API-Key |
| 401 | invalid_token |
Token or key invalid, expired or revoked |
| 403 | insufficient_scope |
API key without the required scope; the body names required_scope |
| 403 | team_membership_ended |
The user was removed from the team the credential is for |
| 403 | PASSWORD_CHANGE_REQUIRED |
The account must change its initial password first |
| 404 | endpoint_not_found |
Path not routed by the gateway |
| 429 | rate_limit_exceeded |
Per-team limit; see Rate Limits |
| 503 | service_unavailable |
The gateway could not reach the identity service; Retry-After is set |
A 504 means the service did not answer within 60 seconds (see Tool Execution).
The tools service answers its errors in the shape every Wildbox service uses:
{
"error": {
"code": 404,
"message": "Task not found",
"type": "HTTPException",
"request_id": "6f1c2d..."
}
}
details is added when there is more to say, such as the field errors of a
- A field error is
{"type", "loc", "msg"}: where the error is and what is wrong. The value that was refused is never in it.request_idmatches theX-Request-IDthe gateway set, for finding the request in the logs.
| Status | Where |
|---|---|
| 400 | Run: target refused by the network target policy. Cancel: task already finished or canceled |
| 403 | Run: tool refused the caller. Run or cancel: the service’s own check of tools:execute (error.details.code INSUFFICIENT_SCOPE or GATEWAY_AUTH_TYPE_REQUIRED) |
| 404 | Unknown tool; task not found or not the caller’s |
| 408 | Synchronous run timed out |
| 422 | Request body missing, not an object, or not matching the input schema |
| 500 | Tool failed |
| 503 | Asynchronous execution unavailable (Redis, the result backend or the task queue down). Run: the caller’s hourly allowance cannot be counted |
Examples
Run a Tool Asynchronously and Wait for Its Result
CA=open-security-gateway/ssl/wildbox.crt
TASK_ID=$(curl -s --cacert "$CA" -X POST https://<host>/api/v1/tools/hash_generator/async \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"input_text": "wildbox", "hash_types": ["sha256"]}' | jq -r '.task_id')
echo "Task submitted: $TASK_ID"
while true; do
TASK=$(curl -s --cacert "$CA" "https://<host>/api/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $TOKEN")
STATUS=$(echo "$TASK" | jq -r '.status')
echo "Status: $STATUS"
if [ "$STATUS" != "pending" ] && [ "$STATUS" != "running" ] && [ "$STATUS" != "retrying" ]; then
echo "$TASK" | jq '{status, error, result}'
break
fi
sleep 2
done
Queue Several Lookups and List Them
CA=open-security-gateway/ssl/wildbox.crt
for domain in example.com example.org; do
curl -s --cacert "$CA" -X POST "https://<host>/api/v1/tools/whois_lookup/async" \
-H "X-API-Key: $WILDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"domain\": \"$domain\"}" | jq -r '.task_id'
done
curl -s --cacert "$CA" "https://<host>/api/v1/tasks" \
-H "X-API-Key: $WILDBOX_API_KEY" \
| jq '.tasks[] | {task_id, tool_name, status}'
Related Documentation
- Authentication and sessions - Tokens and API keys
- Security Policy - Authentication requirements
- API Reference Hub - All service endpoints
- Guardian Service API - Asset management
- Responder Service API - Incident response