Audit Commands ​

Audit commands provide access to the GrantFlow audit trail, which records every privileged access event, approval decision, and administrative action. Security teams use these commands to investigate incidents, generate compliance reports, and monitor access patterns.

grantflow audit list ​

Search and retrieve audit log entries for your tenant. This command lets you filter events by type, actor, timeframe, and other criteria to find specific security events or generate reports.

Usage ​

bash
grantflow audit list [--limit <count>] [--action <action-type>] [--actor <user-id>] [--output table|json|yaml]

Parameters ​

  • --limit - Maximum number of events to return (default: 50, max: 1000)
  • --action - Filter by action type (e.g., RoleActivated, AccountCheckout)
  • --actor - Filter by user ID who performed the action
  • --output - Output format (default: table)

Example ​

bash
$ grantflow audit list --limit 100
ID          TIMESTAMP              ACTOR      ACTION           RESOURCE_TYPE  RESOURCE_ID   STATUS   DETAILS
audit-001   2024-10-24T11:30:00Z   user-123   RoleActivated    Role           role-dba      success  Activated for incident response
audit-002   2024-10-24T11:15:00Z   user-456   AccountCheckout  Account        acct-prod-db  success  30 minute checkout for DB maintenance
audit-003   2024-10-24T10:45:00Z   approver-1 Approved         Activation     act-001       success  Approved emergency request

Understanding Audit Events ​

Each audit entry records a security-relevant action taken within GrantFlow. The timestamp reflects when the event occurred according to the server clock, ensuring consistency across different time zones.

The actor column identifies who performed the action using their GrantFlow user ID. For automated system actions, this may show a system account or service principal identifier.

The action column describes what happened. Common action types include RoleActivated, RoleRevoked, AccountCheckout, ActivationApproved, ActivationDenied, ConnectorSync, and AgentConnected. These action types map directly to user and administrator activities.

The resource type and ID identify what the action affected—a specific role, account, activation request, or system component. Together with the action, this gives you complete context about the event.

Filtering by Action Type ​

To focus on specific types of events, use the action filter:

bash
# View only role activations
grantflow audit list --action RoleActivated --limit 100

# Find all approval decisions
grantflow audit list --action Approved --limit 50

# Track account checkouts
grantflow audit list --action AccountCheckout --limit 100

This is particularly useful when investigating specific types of access or generating targeted compliance reports.

Filtering by Actor ​

To track a specific user's activities, filter by their user ID:

bash
# See all actions by a specific user
grantflow audit list --actor user-123 --limit 100

# Combine filters for precise queries
grantflow audit list --actor user-123 --action RoleActivated

This helps during investigations when you need to understand what a particular user accessed and when.

JSON Output for Analysis ​

The JSON format enables programmatic analysis and integration with external tools:

bash
$ grantflow audit list --limit 50 --output json
[
  {
    "id": "audit-001",
    "timestamp": "2024-10-24T11:30:00Z",
    "actor": "user-123",
    "action": "RoleActivated",
    "resourceType": "Role",
    "resourceId": "role-dba",
    "status": "success",
    "details": "Activated for incident response",
    "correlationId": "req-abc123"
  }
]

You can process this data with tools like jq, import it into spreadsheets, or feed it to SIEM systems:

bash
# Count events by action type
grantflow audit list --limit 1000 --output json | jq 'group_by(.action) | map({action: .[0].action, count: length})'

# Find failed events
grantflow audit list --limit 500 --output json | jq '.[] | select(.status == "failed")'

# Export to CSV for spreadsheet analysis
grantflow audit list --limit 1000 --output json | jq -r '.[] | [.timestamp, .actor, .action, .resourceType, .resourceId, .status] | @csv' > audit.csv

Response Metadata ​

The audit list response includes metadata about the query results:

json
{
  "data": [ /* audit events */ ],
  "meta": {
    "total": 5000,
    "filtered": 100,
    "limit": 100,
    "offset": 0
  }
}

The total field shows how many events exist in the audit log overall, while filtered indicates how many matched your filter criteria. The limit and offset fields reflect pagination parameters.

Pagination ​

The CLI returns up to 1000 events per request. For larger result sets, you'll need to make multiple requests using the offset parameter (not currently exposed in the CLI). For comprehensive audit analysis, consider using the web interface's audit viewer or exporting data through the API.

TIP

For regular compliance reporting, consider scheduling a script that exports audit data daily and archives it to your log management system.

Event Details ​

The details column provides human-readable context about each event. This might include the justification provided for a checkout, the comment from an approver, or error messages for failed operations.

For more structured event details, use JSON output where additional fields may be present depending on the event type.

Correlation IDs ​

Each event includes a correlation ID that links related events together. For example, when you request an activation, the request, approval, and provisioning events all share the same correlation ID. This makes it easy to trace an entire workflow through the audit log.

bash
# Find all events related to a specific request
grantflow audit list --output json | jq '.[] | select(.correlationId == "req-abc123")'

Status Field ​

The status field indicates whether the action succeeded or failed:

A success status means the action completed as intended. For activation requests, this means the system successfully created the request. For approvals, it means the approval was recorded and provisioning began.

A failure status indicates something went wrong. The details field typically contains an error message explaining what failed. Common failures include validation errors, permission denials, or downstream system issues.

Audit Retention ​

GrantFlow retains audit logs according to your tenant's retention policy, typically 90 days for standard tiers and up to 7 years for compliance tiers. Check with your administrator about your specific retention period.

For long-term archival, export audit data regularly to your own storage or SIEM system.

Security and Compliance ​

The audit log is immutable—once an event is recorded, it cannot be modified or deleted. This ensures a tamper-proof record of all privileged access for forensic analysis and compliance auditing.

All access to the audit log itself is logged. When you run audit commands, GrantFlow records that you viewed audit data, including what filters you applied and how many records you retrieved.

DANGER

Audit data may contain sensitive information about system access patterns. Handle exported audit logs according to your organization's data classification policies.

Common Use Cases ​

Here are some common ways security teams use the audit commands:

Incident Response ​

During a security incident, you can quickly identify what access was granted and who used it:

bash
# Find all activations in the last hour
grantflow audit list --action RoleActivated --limit 100

# Track a specific user's recent activity
grantflow audit list --actor suspected-user --limit 500

Compliance Reporting ​

For compliance audits, generate reports showing privileged access patterns:

bash
# Export all activations for quarterly review
grantflow audit list --action RoleActivated --limit 1000 --output json > quarterly-activations.json

# Count checkout events by user
grantflow audit list --action AccountCheckout --limit 1000 --output json | jq 'group_by(.actor) | map({user: .[0].actor, count: length})'

Access Reviews ​

Managers can review their team's privileged access:

bash
# See all approvals you've made
grantflow audit list --actor your-user-id --action Approved --limit 200

# Track activations for your team members
for user in user-1 user-2 user-3; do
  grantflow audit list --actor "$user" --action RoleActivated --limit 50
done