<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# CloudTrail Anomalies — API Reference

## AWS CLI Commands

### CloudTrail Management

```bash
# List trails
aws cloudtrail describe-trails

# Get trail status
aws cloudtrail get-trail-status --name TRAIL_NAME

# Lookup events by attribute
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=EVENT
aws cloudtrail lookup-events --lookup-attributes AttributeKey=Username,AttributeValue=USER
aws cloudtrail lookup-events --lookup-attributes AttributeKey=ResourceType,AttributeValue=AWS::S3::Bucket

# Time-bounded lookup
aws cloudtrail lookup-events --start-time "2026-03-01T00:00:00Z" --end-time "2026-03-17T00:00:00Z"
```

### Athena Queries

```sql
-- Create CloudTrail table
CREATE EXTERNAL TABLE cloudtrail_logs (
  eventversion STRING, useridentity STRUCT<type:STRING,arn:STRING,accountid:STRING>,
  eventtime STRING, eventsource STRING, eventname STRING,
  awsregion STRING, sourceipaddress STRING, useragent STRING,
  errorcode STRING, requestparameters STRING, responseelements STRING
) ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe'
LOCATION 's3://CLOUDTRAIL_BUCKET/AWSLogs/ACCOUNT_ID/CloudTrail/';

-- Top API callers
SELECT useridentity.arn, COUNT(*) as cnt FROM cloudtrail_logs
WHERE eventtime > date_add('day', -7, now()) GROUP BY useridentity.arn ORDER BY cnt DESC LIMIT 20;

-- Error analysis
SELECT errorcode, eventname, COUNT(*) as cnt FROM cloudtrail_logs
WHERE errorcode IS NOT NULL AND eventtime > date_add('day', -7, now())
GROUP BY errorcode, eventname ORDER BY cnt DESC LIMIT 50;
```

### GuardDuty

```bash
# List detectors
aws guardduty list-detectors

# List findings (high severity)
aws guardduty list-findings --detector-id DETECTOR_ID \
  --finding-criteria '{"Criterion":{"severity":{"Gte":7}}}'

# Get finding details
aws guardduty get-findings --detector-id DETECTOR_ID --finding-ids FINDING_ID
```

## boto3 API

| Method | Description |
|--------|-------------|
| `cloudtrail.lookup_events(LookupAttributes=, StartTime=)` | Search events |
| `cloudtrail.describe_trails()` | List trail configurations |
| `cloudtrail.get_trail_status(Name=)` | Trail logging status |
| `guardduty.list_findings(DetectorId=, FindingCriteria=)` | GuardDuty findings |
| `athena.start_query_execution(QueryString=, ResultConfiguration=)` | Run Athena query |

## Key CloudTrail Event Fields

| Field | Description |
|-------|-------------|
| `eventTime` | UTC timestamp |
| `eventName` | API action name |
| `userIdentity.arn` | Caller identity ARN |
| `sourceIPAddress` | Origin IP |
| `awsRegion` | Region where event occurred |
| `errorCode` | Error if request failed |
| `requestParameters` | API request parameters |
| `responseElements` | API response data |
