Ethical Hacking Tools Explained

A single API key leak can turn an authenticated tool into an open door. This section documents how to generate, store, and use API keys for authenticated requests (login + API key authentication) in security tools, with concrete parameters and response shapes.

Overview

This section covers API key authentication for tool actions: generating keys, sending them on requests, and validating responses that confirm authentication. Use it when a tool provides an API (REST/JSON) and expects a key in headers or query parameters.

Quick Reference

Key format expectation (typical): `ApiKey :` or a single secret string. Follow the tool’s API docs for the exact scheme.

Parameters

Code Example

import os
import json
import requests

# Assumptions:
# - Environment variable holds the API key secret.
# - The API expects: Authorization: ApiKey 
API_BASE = "https://api.example-tool.com/v1"
API_KEY = os.environ["TOOL_API_KEY"]  # store in secrets manager, not source code

headers = {
    "Authorization": f"ApiKey {API_KEY}",
    "Content-Type": "application/json",
    # "X-Request-Id": "uuid-here"  # optional correlation id
}

payload = {
    "job_name": "web-scan-prod",
    "target": "https://example.com",
    "options": {
        "checks": ["headers", "tls", "auth-misconfig"],
        "max_depth": 2
    },
    "timeout_ms": 30000
}

# Create an authenticated job (tool action)
resp = requests.post(f"{API_BASE}/scan/jobs", headers=headers, data=json.dumps(payload), timeout=35)
resp.raise_for_status()
job = resp.json()

job_id = job["job_id"]

# Poll job status using the same API key
status_resp = requests.get(f"{API_BASE}/scan/jobs/{job_id}", headers=headers, timeout=35)
status_resp.raise_for_status()
print(status_resp.json())

Response Format

{
  "job_id": "job_9f3c2a1b",
  "status": "queued",
  "created_at": "2026-06-03T10:20:30Z",
  "auth": {
    "scheme": "ApiKey",
    "key_fingerprint": "sha256:ab12cd34..." 
  },
  "results": null,
  "errors": []
}

Field notes

• `status`: common values include `queued`, `running`, `completed`, `failed`.
• `auth.key_fingerprint`: server-side verification hint; never treat it as the secret.
• `results`: populated only after `completed`.
• `errors`: array of structured error objects (code/message/details).

Notes & Best Practices

• Rate limits: respect `429` responses; implement exponential backoff using a bounded retry count (e.g., max 5 retries).
• Error handling: on `401/403`, treat as authentication failure (wrong key, revoked key, or missing `Authorization` header).
• Key scope: prefer least-privilege keys (separate keys for read-only job status vs. job creation).
• Transport security: require HTTPS; reject plaintext or mixed-content endpoints in client configuration.

This chapter’s KeyLock Authentication Map focuses on headers, parameters, and response shapes that keep authenticated tool actions consistent - next, you’ll extend this into safe key lifecycle management (rotation and revocation) so authenticated access stays controlled over time.