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
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
$ 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:
# 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:
# 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:
$ 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:
# 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:
{
"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.
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.
# 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.
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:
# 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:
# 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:
# 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
Related Topics
- Activity Log - Web interface for browsing audit events
- Audit Events - Administrator guide to audit configuration
- Activation Commands - Generate audit events through role activations
- Account Commands - Account checkout events in the audit log