Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Bucket A: HTTPS API migration

Bucket A handles migrations where your applications call a cloud secret store API (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, AWS SSM) directly over HTTPS. The KnoxCall agent intercepts these calls before they leave the host, rewrites the authentication header, and returns the secret from KnoxCall instead. Your application code does not change.

​
How it works

Application
  ↓  HTTPS call to secretsmanager.us-east-1.amazonaws.com
KnoxCall agent (intercept mode)
  ↓  Validates app identity (SO_PEERCRED or process UID)
  ↓  Rewrites auth header: AWS SigV4 → KnoxCall Bearer token
  ↓  Forwards to KnoxCall proxy
KnoxCall proxy
  ↓  Injects real secret value
  ↓  Returns response in AWS SM wire format
Application receives response — identical to a real AWS SM response
The agent acts as a transparent MITM on the loopback interface. The application’s AWS SDK believes it’s talking to AWS Secrets Manager; the agent translates the call to KnoxCall’s API and returns a response in the expected format. No plaintext secret value ever touches disk. The agent holds secrets in memory only for the duration of the intercept.

​
Supported capture surfaces

SurfaceHow interception works
K8s CSI volume driverAgent sidecar intercepts filesystem reads from the CSI mount
External Secrets Operator (ESO)Agent intercepts ESO’s API calls to the provider
ECS / Lambda environment injectionAgent intercepts metadata endpoint calls at runtime
Cloud sidecar agentsAgent intercepts AWS AppConfig, Azure App Configuration, GCP Config Connector calls
TLS interceptionAgent proxies all outbound TLS on configured ports; matches secret store hostnames

​
Setting up intercept rules

Intercept rules tell the agent which outbound requests to intercept and how to rewrite them.

​
Via admin UI

  1. Go to Infrastructure → Secret Store Migrations
  2. Open the migration → click the Intercept Rules tab
  3. Click Add rule
  4. Configure:
    • Match host: e.g. secretsmanager.us-east-1.amazonaws.com
    • Match path prefix: e.g. /
    • Rewrite: select the KnoxCall secret to substitute
  5. Save — the agent picks up new rules within 30 seconds

​
Example rule (AWS SM → KnoxCall)

{
  "match_host": "secretsmanager.us-east-1.amazonaws.com",
  "match_path_prefix": "/",
  "rewrite_secret_id": "sec_01abc...",
  "response_format": "aws_secrets_manager"
}
The response_format field tells the agent to return the value in the format the application expects (AWS SM JSON envelope, plain value, Azure KV JSON, etc.).

​
Zero-plaintext guarantee

  • The secret value is never written to disk, logged, or stored in the migration_intercept_rules table
  • The agent holds the value in memory only for the lifespan of a single request
  • If the agent process crashes mid-intercept, the application receives a connection error — not a partial or logged secret

​
Monitoring migration progress

The secret_consumers table tracks discovered workloads that are consuming each migrated secret: 
curl https://api.knoxcall.com/admin/migrations/mgr_01abc.../verification-events \
  -H "Authorization: Bearer $KC_ADMIN_JWT"
The admin UI shows a consumer count per secret, and highlights any consumers not yet seen through the intercept path.

​
Migration status progression

StatusWhat it means
pendingMigration created; discovery not yet started
discoveringAgent scanning workloads; no interception active yet
awaiting_reviewDiscovery complete; items queued for reviewer decisions
completedAll approved items committed to KnoxCall secrets

​
Cutover

When the verification dashboard shows all consumers green and all items have been approved:
  1. In the admin UI, click Commit migration (or call POST /admin/migrations/:id/commit)
  2. Wait for the completed status
  3. You can now safely revoke cloud store credentials and remove secrets from the source provider
Do not revoke the cloud store credentials until you have confirmed all application instances are routing through KnoxCall. Intercept rules route live traffic — removing them before cutover confirmation will break applications.

​
Cancelling a Bucket A migration

You can cancel a migration in pending, discovering, or awaiting_review state: 
curl -X POST https://api.knoxcall.com/admin/migrations/mgr_01abc.../cancel \
  -H "Authorization: Bearer $KC_ADMIN_JWT"
This removes all intercept rules. Applications revert to direct cloud store access immediately.

Bucket B: Database migration

For database credentials

Migration verification

DNS/TLS probes and safe-to-delete confirmation

Migrations API reference

Intercept rules and migration endpoints

Migrations overview

Back to overview