Custom command

The command lease backend runs an arbitrary script or command to create (and optionally revoke) credentials. Use this for systems that fnox doesn't natively support.

Configuration

[leases.custom]
type = "command"
create_command = "./scripts/get-creds.sh"
revoke_command = "./scripts/revoke-creds.sh"  # optional
duration = "1h"

Field	Required	Description
create_command	Yes	Shell command to create credentials (run via sh -c)
revoke_command	No	Shell command to revoke credentials (run via sh -c)
duration	No	Lease duration (e.g., "1h", "30m"; default: "15m")
timeout	No	Command execution timeout (default: "30s")

Prerequisites

None — fnox can't validate prerequisites without running the command.

Create command

Your script receives these environment variables:

Variable	Description
FNOX_LEASE_DURATION	Requested duration in seconds
FNOX_LEASE_LABEL	Lease label (default: fnox-lease)

The script must output JSON on stdout and exit successfully. Send diagnostics to stderr. Ensure expires_at matches the real credential expiry; omitting it produces a lease with no tracked expiry, even when duration was requested:

{
  "credentials": {
    "MY_TOKEN": "tok-abc123",
    "MY_SECRET": "sec-xyz789"
  },
  "expires_at": "2030-01-15T10:00:00Z",
  "lease_id": "my-custom-lease-1"
}

Field	Required	Description
credentials	Yes	Key-value map of env var name to credential value (values must be strings; at least one is required)
expires_at	No	Expiry timestamp (RFC3339). Omit for never-expiring leases.
lease_id	No	Unique lease ID. Auto-generated if omitted.

The timestamp above is illustrative. Generate it from the actual credential response, rather than copying a fixed date into a script.

Revoke command

If revoke_command is set, it's called when you run fnox lease revoke or fnox lease cleanup. It receives:

Variable	Description
FNOX_LEASE_ID	Lease ID to revoke

Limits

• Max duration: 24 hours
• Revocation: Only if revoke_command is configured

Examples

Basic script

#!/bin/bash
set -euo pipefail
# scripts/get-creds.sh

# Call your internal API
RESPONSE=$(curl -fsS https://creds.internal/api/token \
  --header "Authorization: Bearer $INTERNAL_AUTH" \
  --data "ttl=$FNOX_LEASE_DURATION")

# Output JSON
echo "$RESPONSE"

Generate JSON from CLI output with jq

Many CLIs output credentials in non-JSON formats. Use jq to reshape the output:

#!/bin/bash
set -euo pipefail
# scripts/get-k8s-token.sh

TOKEN=$(kubectl create token my-service-account \
  --duration="${FNOX_LEASE_DURATION}s" 2>/dev/null)

EXPIRY=$(date -u -d "+${FNOX_LEASE_DURATION} seconds" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
  || date -u -v+${FNOX_LEASE_DURATION}S +%Y-%m-%dT%H:%M:%SZ)

jq -n \
  --arg token "$TOKEN" \
  --arg exp "$EXPIRY" \
  '{
    credentials: { KUBE_TOKEN: $token },
    expires_at: $exp
  }'

[leases.k8s]
type = "command"
create_command = "./scripts/get-k8s-token.sh"
duration = "1h"

With revocation

#!/bin/bash
set -euo pipefail
# scripts/get-creds.sh

LEASE_ID="custom-$(date +%s)"
TOKEN=$(my-tool create-token --ttl "$FNOX_LEASE_DURATION")

jq -n \
  --arg token "$TOKEN" \
  --arg id "$LEASE_ID" \
  '{
    credentials: { API_TOKEN: $token },
    lease_id: $id
  }'

#!/bin/bash
set -euo pipefail
# scripts/revoke-creds.sh

my-tool revoke-token "$FNOX_LEASE_ID"

Wrapping aws sts directly

#!/bin/bash
set -euo pipefail
# scripts/assume-role.sh

aws sts assume-role \
  --role-arn "arn:aws:iam::123456789012:role/my-role" \
  --role-session-name "$FNOX_LEASE_LABEL" \
  --duration-seconds "$FNOX_LEASE_DURATION" \
| jq '{
    credentials: {
      AWS_ACCESS_KEY_ID: .Credentials.AccessKeyId,
      AWS_SECRET_ACCESS_KEY: .Credentials.SecretAccessKey,
      AWS_SESSION_TOKEN: .Credentials.SessionToken
    },
    expires_at: .Credentials.Expiration
  }'

Parsing key=value output

#!/bin/bash
set -euo pipefail
# scripts/get-creds.sh

# Some tools output key=value pairs
OUTPUT=$(my-tool get-creds --format=env)

# Parse into JSON with jq
echo "$OUTPUT" | jq -Rn '
  [inputs | capture("^(?<key>[^=]+)=(?<value>.*)$") | {(.key): .value}] | add |
  { credentials: . }
'

See also

• Credential Leases — overview and approaches