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}/async queues 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, .localdomain or .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

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_HOUR requests 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 carries X-RateLimit-Limit (the per-minute figure), X-RateLimit-Remaining and X-RateLimit-Reset, which describe the current minute, and X-RateLimit-Policy: <per hour>;w=3600. Past the limit the gateway answers 429 with Retry-After and {"error": "rate_limit_exceeded", "message": "Rate limit exceeded", "limit_per_hour": 10000, "retry_after_seconds": ...}. RATE_LIMIT_PER_HOUR is set in .env and passed to the gateway by docker-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_req zone global, 100 requests per second with a burst of 10, answered with 429. The rate is the gateway’s GATEWAY_RATE_LIMIT_PER_SECOND setting, 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

  1. 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_id matches the X-Request-ID the 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}'