Module token_analysis

vault_audit_tools::commands

Module token_analysis 

Source
Expand description

Unified token analysis command.

Consolidates token operations tracking, abuse detection, and data export into a single powerful command. Supports multi-file analysis (compressed or uncompressed) for comprehensive token usage analysis.

§Usage

# Overview of all token operations by entity
vault-audit token-analysis logs/*.log
vault-audit token-analysis logs/*.log.gz

# Detect token lookup abuse (default threshold: 1000)
vault-audit token-analysis logs/*.log --abuse-threshold 1000

# Filter specific operation types
vault-audit token-analysis logs/*.log --filter lookup
vault-audit token-analysis logs/*.log --filter create,renew

# Export to CSV for further analysis
vault-audit token-analysis logs/*.log --export token_data.csv

# Export only high-volume token accessors (individual tokens)
vault-audit token-analysis logs/*.log --min-operations 1000 --export high_volume_tokens.csv

# Combine abuse detection with export
vault-audit token-analysis logs/*.log --abuse-threshold 500 --export abuse_patterns.csv

Compressed File Support: Automatically handles .gz and .zst files.

§Understanding Entities vs Accessors

  • Entity: A user or service identity (e.g., “fg-PIOP0SRVDEVOPS”)

    • One entity can have multiple tokens over time
    • Summary view shows per-entity totals

  • Accessor: A unique token identifier (individual token)

    • Each accessor belongs to one entity
    • CSV export shows per-accessor detail with timestamps
    • Example: An entity with 100k operations might have 3 accessors with 50k, 30k, 20k operations each

§Output Modes

§Default: Operations Summary (Per-Entity)

Displays aggregated breakdown of all token operations by entity:

  • lookup-self, renew-self, revoke-self, create, login, other
  • Shows top 50 entities sorted by total operations
  • One row per entity (combines all tokens for that entity)

§Abuse Detection Mode (–abuse-threshold)

Identifies entities exceeding lookup threshold:

  • Entity details and lookup count
  • Time range and rate (lookups/hour)
  • Helps find misconfigured apps or compromised credentials

§Export Mode (–export) - Per-Accessor Detail

Generates CSV with per-token accessor granularity:

  • entity_id, display_name, accessor (token identifier)
  • operations, first_seen, last_seen, duration_hours
  • Shows individual token lifecycle and usage patterns
  • Use –min-operations to filter low-activity tokens
  • First/last seen timestamps
  • Duration

Functions§

run
Main entry point for token analysis command