id: apache-polaris-stale-principal-credential-rotation-guard
namespace: company.data
description: |
Audit Apache Polaris service principals for credentials that have not been
rotated within a configurable age window, a real security-hygiene gap since
Polaris itself has no built-in alerting on credential age. Track rotation
history per principal in Kestra KV (Polaris's own lastUpdateTimestamp
reflects any metadata change, not specifically rotation, so it is not a
reliable signal on its own), pause for operator approval, rotate credentials
via the Polaris management API, and confirm the call succeeded without ever
surfacing the newly generated secret in a log, Slack message, or KV entry.
inputs:
- id: polaris_url
type: STRING
displayName: Polaris Server URL
description: Base HTTP(S) URL of the Polaris server (default port 8181), e.g.
https://polaris.internal:8181.
defaults: "http://localhost:8181"
- id: polaris_bearer_token
type: STRING
displayName: Polaris Bearer Token
description: A valid OAuth2 bearer token for the Polaris management API,
obtained via your own identity provider flow. Polaris's built-in
/v1/oauth/tokens endpoint is documented as deprecated for removal, so this
blueprint does not implement a token exchange itself; supply an
already-valid token here (for example minted by a scheduled upstream task
against your configured oauth2-server-uri).
defaults: "{{ secret('POLARIS_BEARER_TOKEN') }}"
- id: exclude_principals
type: ARRAY
itemType: STRING
displayName: Excluded Principals
description: Principal names that must never be flagged or rotated by this
guard, for example your bootstrap or break-glass service principal. Empty
by default; populate with your environment's protected principal names
before enabling auto_remediate.
defaults: []
- id: max_credential_age_days
type: INT
displayName: Max Credential Age (Days)
description: Credential age in days at or above which a principal is flagged for
rotation. A principal never rotated by this flow before is evaluated
against its Polaris createTimestamp as the baseline.
defaults: 90
- id: max_rotations_per_run
type: INT
displayName: Max Rotations Per Run
description: Safety ceiling on the number of principals rotated in a single
execution pass. When more principals qualify, the oldest credentials are
prioritized and the rest deferred to the next run.
defaults: 1
- id: cursor_key
type: STRING
displayName: KV Cursor Key
description: Kestra KV key used to persist per-principal rotation history across
runs. Contains principal names and timestamps only, never credential
material.
defaults: "polaris_principal_rotation_tracker"
- id: dry_run
type: BOOL
displayName: Dry Run Mode
description: When true, audits credential age and logs the proposed rotations
without mutating any principal's credentials.
defaults: true
- id: auto_remediate
type: BOOL
displayName: Auto Remediate
description: When true and dry_run is false, pauses for operator approval and
then calls the Polaris rotateCredentials API on verified stale principals.
defaults: false
triggers:
- id: periodic_credential_age_audit
type: io.kestra.plugin.core.trigger.Schedule
description: Audit principal credential age every day. Shipped disabled so the
flow can be verified manually in safe mode first.
cron: "0 6 * * *"
disabled: true
- id: on_demand_audit_webhook
type: io.kestra.plugin.core.trigger.Webhook
description: Authenticated HTTP endpoint invoked by a security review runbook or
compliance audit trigger.
key: "{{ secret('POLARIS_GUARD_WEBHOOK_KEY') }}"
tasks:
- id: validate_inputs
type: io.kestra.plugin.core.execution.Assert
description: Assert operational thresholds satisfy sanity constraints before
calling the Polaris management API.
conditions:
- "{{ inputs.max_credential_age_days >= 1 }}"
- "{{ inputs.max_rotations_per_run >= 1 }}"
errorMessage: "Invalid configuration: max_credential_age_days and
max_rotations_per_run must both be at least 1."
- id: list_principals
type: io.kestra.plugin.core.http.Request
description: List all Polaris service principals via the management API.
uri: "{{ inputs.polaris_url }}/api/management/v1/principals"
method: GET
headers:
Accept: application/json
options:
auth:
type: BEARER
token: "{{ inputs.polaris_bearer_token }}"
- id: triage_principals
type: io.kestra.plugin.scripts.python.Script
description: Classify principals by credential age against historical KV
rotation state, excluding protected principals and applying the
max_rotations_per_run safety cap.
containerImage: python:3.11-slim
env:
PRINCIPALS_BODY: "{{ outputs.list_principals.body is defined ?
outputs.list_principals.body : '{}' }}"
EXCLUDE_PRINCIPALS: "{{ inputs.exclude_principals | toJson }}"
MAX_CREDENTIAL_AGE_DAYS: "{{ inputs.max_credential_age_days }}"
MAX_ROTATIONS_PER_RUN: "{{ inputs.max_rotations_per_run }}"
EXECUTION_ID: "{{ execution.id }}"
PREVIOUS_STATE_JSON: "{{ kv(inputs.cursor_key, errorOnMissing=false) ?? '{}' }}"
script: |
import json
import os
from datetime import datetime, timezone
try:
from kestra import Kestra
except ImportError:
Kestra = None
now_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
now_iso = datetime.now(timezone.utc).isoformat()
principals_body_raw = os.environ.get("PRINCIPALS_BODY", "{}")
exclude_principals = set(json.loads(os.environ.get("EXCLUDE_PRINCIPALS", "[]")))
max_credential_age_days = int(os.environ.get("MAX_CREDENTIAL_AGE_DAYS", "90"))
max_rotations_per_run = int(os.environ.get("MAX_ROTATIONS_PER_RUN", "1"))
execution_id = os.environ.get("EXECUTION_ID", "manual")
prev_state_raw = os.environ.get("PREVIOUS_STATE_JSON", "{}")
try:
prev_state = json.loads(prev_state_raw) if prev_state_raw.strip() else {}
except Exception:
prev_state = {}
try:
principals_data = json.loads(principals_body_raw) if principals_body_raw.strip() else {}
except Exception:
principals_data = {}
principal_list = principals_data.get("principals", []) if isinstance(principals_data, dict) else []
new_state_snapshot = {}
rotation_candidates = []
excluded_count = 0
healthy_count = 0
for p in principal_list:
if not isinstance(p, dict):
continue
name = str(p.get("name", ""))
if not name:
continue
if name in exclude_principals:
excluded_count += 1
continue
create_ts = int(p.get("createTimestamp", 0) or 0)
prev_entry = prev_state.get(name, {})
# Authoritative signal is this flow's own rotation history, since Polaris's
# lastUpdateTimestamp reflects ANY principal metadata change (property
# updates, role grants), not specifically credential rotation, and is not
# a reliable proxy for rotation age. A principal with no prior rotation by
# this flow falls back to createTimestamp: "credentials have existed
# since creation, rotation history before adoption is unknown."
last_rotated_by_flow_ms = prev_entry.get("last_rotated_by_flow_ms")
effective_last_rotated_ms = last_rotated_by_flow_ms if last_rotated_by_flow_ms is not None else create_ts
age_days = (now_ms - effective_last_rotated_ms) / 86400000.0 if effective_last_rotated_ms > 0 else None
new_state_snapshot[name] = {
"last_rotated_by_flow_ms": last_rotated_by_flow_ms,
"create_timestamp_ms": create_ts,
"last_evaluated_at": now_iso,
}
if age_days is not None and age_days >= max_credential_age_days:
rotation_candidates.append({
"principal_name": name,
"age_days": round(age_days, 1),
"basis": "flow_tracked_rotation" if last_rotated_by_flow_ms is not None else "create_timestamp_fallback",
})
else:
healthy_count += 1
# Cap at max_rotations_per_run, oldest credentials first.
rotation_candidates.sort(key=lambda c: c["age_days"], reverse=True)
selected_candidates = rotation_candidates[:max_rotations_per_run]
deferred_candidates = rotation_candidates[max_rotations_per_run:]
has_candidates = len(selected_candidates) > 0
overall_status = "WARNING" if has_candidates else ("INFO" if deferred_candidates else "HEALTHY")
summary_lines = [
f"- `{c['principal_name']}`: credentials {c['age_days']} day(s) old (basis: {c['basis']})"
for c in selected_candidates
]
if deferred_candidates:
summary_lines.append(f"Deferred by max_rotations_per_run cap: {len(deferred_candidates)} additional stale principal(s) not included this pass.")
summary_text = (
f"Polaris Credential Rotation Guard: {overall_status} | "
f"Audited {len(principal_list)} principal(s) ({excluded_count} excluded). "
f"Rotation candidates: {len(selected_candidates)}. Deferred: {len(deferred_candidates)}. "
f"Healthy: {healthy_count}."
)
print(summary_text)
audit_manifest = {
"overall_status": overall_status,
"principals_audited": len(principal_list),
"excluded_count": excluded_count,
"rotation_candidate_count": len(selected_candidates),
"deferred_count": len(deferred_candidates),
"healthy_count": healthy_count,
# Deliberately contains only principal names and ages, never any credential
# material -- rotateCredentials' response (the new secret) is never
# referenced anywhere in this flow's outputs, logs, or KV writes.
"rotation_candidates": selected_candidates,
"execution_id": execution_id,
"evaluated_at": now_iso,
"summary": summary_text,
}
output_data = {
"has_rotation_candidates": has_candidates,
"rotation_candidate_count": len(selected_candidates),
"overall_status": overall_status,
"rotation_candidates": selected_candidates,
"summary": summary_text,
"summary_details": "\n".join(summary_lines) if summary_lines else "None",
"new_state_snapshot": new_state_snapshot,
"audit_manifest": audit_manifest,
}
if Kestra:
Kestra.outputs(output_data)
else:
print("::" + json.dumps({"outputs": output_data}) + "::")
- id: save_tracker_kv
type: io.kestra.plugin.core.kv.Set
description: Persist the baseline per-principal rotation state into Kestra KV.
Updated again after any rotation below to record the new rotation
timestamp.
key: "{{ inputs.cursor_key }}"
value: "{{ outputs.triage_principals.vars.new_state_snapshot | toJson }}"
kvType: JSON
- id: evaluate_stale_credentials
type: io.kestra.plugin.core.flow.If
description: Branch execution based on whether any principal's credentials
exceed the configured age threshold.
condition: "{{ outputs.triage_principals.vars.has_rotation_candidates == true }}"
then:
- id: dispatch_slack_alert
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Deliver triage notification to Slack naming stale principals and
their credential age. Never includes any credential material.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"attachments": [
{
"color": "warning",
"title": ":warning: Apache Polaris Stale Credential Alert",
"text": "*Status:* `{{ outputs.triage_principals.vars.overall_status }}`\n*Server:* `{{ inputs.polaris_url }}`\n*Rotation Candidates:* {{ outputs.triage_principals.vars.rotation_candidate_count }}\n*Mode:* auto_remediate={{ inputs.auto_remediate }}, dry_run={{ inputs.dry_run }}\n*Execution:* `{{ execution.id }}`\n\n*Details:*\n{{ outputs.triage_principals.vars.summary_details }}\n\n*Summary:* {{ outputs.triage_principals.vars.summary }}"
}
]
}
- id: remediation_mode_gate
type: io.kestra.plugin.core.flow.If
description: Gate automated remediation behind auto_remediate and dry_run
configuration flags.
condition: "{{ inputs.auto_remediate and not inputs.dry_run }}"
then:
- id: pause_for_operator_approval
type: io.kestra.plugin.core.flow.Pause
description: Pause workflow execution for operator review before rotating
principal credentials. Resume to apply or kill to abort; no
timeout is set so this waits indefinitely for a human decision.
Apache Polaris maintains the prior credential as a secondary
secret that remains valid after rotation, so this is a graceful
rotation rather than an instant cutover, but downstream consumers
should still be coordinated before approving.
onResume:
- id: approved
type: BOOL
defaults: false
description: Set true to confirm the Polaris rotateCredentials call should be
issued against the flagged stale principals.
- id: branch_on_approval
type: io.kestra.plugin.core.flow.If
description: Execute rotation only if explicit human approval was provided
during the pause gate.
condition: "{{ outputs.pause_for_operator_approval.onResume.approved == true }}"
then:
- id: rotate_stale_principals
type: io.kestra.plugin.core.flow.Loop
description: Iterate sequentially over rotation candidates and rotate each
principal's credentials.
concurrencyLimit: 1
values: "{{ outputs.triage_principals.vars.rotation_candidates | toJson }}"
tasks:
- id: rotate_credentials
type: io.kestra.plugin.core.http.Request
description: Call Polaris's rotateCredentials endpoint. The response body
contains a newly generated client secret; this flow
deliberately never references
outputs.rotate_credentials.body anywhere downstream, only
its HTTP status code is used to confirm success.
uri: "{{ inputs.polaris_url }}/api/management/v1/principals/{{
fromJson(item.value).principal_name }}/rotate"
method: POST
options:
auth:
type: BEARER
token: "{{ inputs.polaris_bearer_token }}"
- id: assert_rotation_succeeded
type: io.kestra.plugin.core.execution.Assert
description: Confirm the rotation call returned a successful HTTP status,
without inspecting the response body.
conditions:
- "{{ outputs.rotate_credentials.code == 200 }}"
errorMessage: "Polaris rotateCredentials call for principal {{
fromJson(item.value).principal_name }} did not return HTTP
200 (got {{ outputs.rotate_credentials.code }}). Check
that the bearer token has permission to rotate credentials
and that the principal still exists."
- id: log_principal_rotated
type: io.kestra.plugin.core.log.Log
description: Record successful rotation for this principal. Logs only the
principal name and prior age, never credential material.
message: "Rotated credentials for principal {{
fromJson(item.value).principal_name }} (credentials were
{{ fromJson(item.value).age_days }} day(s) old)."
- id: mark_rotated_in_kv
type: io.kestra.plugin.scripts.python.Script
description: Merge the successfully rotated principals' new rotation timestamp
into the baseline KV snapshot, leaving every other principal's
tracked state untouched.
containerImage: python:3.11-slim
env:
BASE_SNAPSHOT_JSON: "{{ outputs.triage_principals.vars.new_state_snapshot |
toJson }}"
ROTATED_PRINCIPALS_JSON: "{{ outputs.triage_principals.vars.rotation_candidates
| toJson }}"
script: |
import json
import os
import time
try:
from kestra import Kestra
except ImportError:
Kestra = None
base = json.loads(os.environ.get("BASE_SNAPSHOT_JSON", "{}"))
rotated = json.loads(os.environ.get("ROTATED_PRINCIPALS_JSON", "[]"))
now_ms = int(time.time() * 1000)
for r in rotated:
name = r.get("principal_name")
if name in base:
base[name]["last_rotated_by_flow_ms"] = now_ms
output_data = {"merged_snapshot": base}
if Kestra:
Kestra.outputs(output_data)
else:
print("::" + json.dumps({"outputs": output_data}) + "::")
- id: save_rotated_tracker_kv
type: io.kestra.plugin.core.kv.Set
description: Persist the merged rotation state, recording the new rotation
timestamp for principals rotated this run.
key: "{{ inputs.cursor_key }}"
value: "{{ outputs.mark_rotated_in_kv.vars.merged_snapshot | toJson }}"
kvType: JSON
- id: save_audit_kv
type: io.kestra.plugin.core.kv.Set
description: Persist the rotation audit manifest into Kestra KV for compliance
review. Contains only principal names and ages, never
credential material.
key: "polaris_rotation_audit_{{ execution.id }}"
value: "{{ outputs.triage_principals.vars.audit_manifest | toJson }}"
kvType: JSON
- id: notify_resolution_slack
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Dispatch resolution confirmation to Slack once all approved stale
principals have been rotated.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"attachments": [
{
"color": "#2EB67D",
"title": ":white_check_mark: Apache Polaris Credentials Rotated",
"text": "*Server:* `{{ inputs.polaris_url }}`\n*Principals Rotated:* `{{ outputs.triage_principals.vars.rotation_candidate_count }}`\n*Execution:* `{{ execution.id }}`\n*Note:* Prior credentials remain valid as a secondary secret; coordinate downstream consumer updates before the next rotation cycle."
}
]
}
else:
- id: log_approval_declined
type: io.kestra.plugin.core.log.Log
description: Record that the operator declined approval for rotating stale
credentials.
message: "Operator declined approval for Polaris credential rotation. Flagged
principals were left unrotated."
else:
- id: log_dry_run_plan
type: io.kestra.plugin.core.log.Log
description: Log the planned rotation without mutating any principal's
credentials.
message: |
Dry run active or auto_remediate disabled (dry_run={{ inputs.dry_run }}, auto_remediate={{ inputs.auto_remediate }}).
Planned rotation for {{ outputs.triage_principals.vars.rotation_candidate_count }} principal(s):
{{ outputs.triage_principals.vars.rotation_candidates | toJson }}
else:
- id: log_healthy_state
type: io.kestra.plugin.core.log.Log
description: Confirm nominal state when no principal's credentials exceed the
configured age threshold.
message: "Apache Polaris credentials nominal on {{ inputs.polaris_url }}. No
principal credentials at or beyond {{ inputs.max_credential_age_days
}} day(s) old."
errors:
- id: alert_on_workflow_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Dispatch emergency alert to Slack if the guard encounters an
unhandled execution error.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"attachments": [
{
"color": "danger",
"title": ":rotating_light: Apache Polaris Credential Rotation Guard Execution Failed",
"text": "Failed execution `{{ execution.id }}` while auditing or rotating credentials on `{{ inputs.polaris_url }}`. Check Polaris connectivity, bearer token validity, and worker logs."
}
]
}
outputs:
- id: principals_audited
type: INT
value: "{{ outputs.triage_principals.vars.audit_manifest.principals_audited ?? 0
}}"
- id: rotation_candidate_count
type: INT
value: "{{ outputs.triage_principals.vars.rotation_candidate_count ?? 0 }}"
- id: status
type: STRING
value: "{{ (outputs.triage_principals.vars.rotation_candidate_count ?? 0) > 0 ?
((inputs.auto_remediate and not inputs.dry_run and
(outputs.pause_for_operator_approval.onResume.approved ?? false)) ?
'REMEDIATED' : 'STALE_CREDENTIALS_DETECTED') : 'HEALTHY' }}"