Skip to content

Conversation

fukusuket
Copy link
Collaborator

@fukusuket fukusuket commented May 31, 2025

What Changed

Evidence

aws-ct-timeline

./suzaku aws-ct-timeline -h
Version: 0.3.0-dev Dev Build
Yamato Security (https://github.com/Yamato-Security/suzaku - @SecurityYamato)

Usage:
  suzaku aws-ct-timeline <INPUT> [OPTIONS]

General Options:
  -r, --rules <DIR/FILE>  Specify a custom rule directory or file (default: ./rules)
  -h, --help              Show the help menu

Input:
  -d, --directory <DIR>  Directory of multiple gz/json files
  -f, --file <FILE>      File path to one gz/json file

Filtering:
      --timeline-start <DATE>  Start time of the event to load (ex: "2022-02-22T23:59:59Z)
      --timeline-end <DATE>    End time of the event to load (ex: "2020-02-22T00:00:00Z")
      --time-offset <OFFSET>   Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)

Output:
  -o, --output <FILE>              Save the results to a file
  -t, --output-type <OUTPUT_TYPE>  Output type 1: CSV (default), 2: JSON, 3: JSONL, 4: CSV & JSON, 5: CSV & JSONL [default: 1]
  -C, --clobber                    Overwrite files when saving
  -G, --GeoIP <MAXMIND-DB-DIR>     Add GeoIP (ASN, city, country) info to IP addresses
  -R, --raw-output                 Output the original JSON logs (only available in JSON formats)

Display Settings:
  -K, --no-color               Disable color output
  -N, --no-summary             Do not display results summary
  -T, --no-frequency-timeline  Disable event frequency timeline (terminal needs to support Unicode)
  -q, --quiet                  Quiet mode: do not display the launch banner

aws-ct-summary

./suzaku aws-ct-summary -h
Version 0.3.0-dev Dev Build
Yamato Security (https://github.com/Yamato-Security/suzaku - @SecurityYamato)

Usage:
  suzaku aws-ct-summary <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple gz/json files
  -f, --file <FILE>      File path to one gz/json file

Filtering:
      --timeline-start <DATE>  Start time of the event to load (ex: "2022-02-22T23:59:59Z)
      --timeline-end <DATE>    End time of the event to load (ex: "2020-02-22T00:00:00Z")
      --time-offset <OFFSET>   Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)
  -s, --include-sts-keys       Include temporary AWS STS access key IDs

Output:
  -o, --output <FILE>           Output results to a CSV file
  -D, --hide-descriptions       Hide description of the commonly abused API calls
  -G, --GeoIP <MAXMIND-DB-DIR>  Add GeoIP (ASN, city, country) info to IP addresses

Display Settings:
  -K, --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner

General Options:
  -h, --help  Show the help menu

aws-ct-metrics

./suzaku aws-ct-metrics -h
Version 0.3.0-dev Dev Build
Yamato Security (https://github.com/Yamato-Security/suzaku - @SecurityYamato)

Usage:
  suzaku aws-ct-metrics <INPUT> [OPTIONS]

Input:
  -d, --directory <DIR>  Directory of multiple gz/json files
  -f, --file <FILE>      File path to one gz/json file

Filtering:
      --timeline-start <DATE>  Start time of the event to load (ex: "2022-02-22T23:59:59Z)
      --timeline-end <DATE>    End time of the event to load (ex: "2020-02-22T00:00:00Z")
      --time-offset <OFFSET>   Scan recent events based on an offset (ex: 1y, 3M, 30d, 24h, 30m)

Output:
  -F, --field-name <FIELD_NAME>  The field to generate metrics for [default: eventName]
  -o, --output <FILE>            Output CSV

Display Settings:
  -K, --no-color  Disable color output
  -q, --quiet     Quiet mode: do not display the launch banner

General Options:
  -h, --help  Show the help menu

I’d appreciate it if you could check it when you have time🙏

@fukusuket fukusuket self-assigned this May 31, 2025
@fukusuket fukusuket added the enhancement New feature or request label May 31, 2025
@fukusuket fukusuket requested a review from Copilot May 31, 2025 14:16
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

Adds a new time-based filtering option to allow CLI consumers to restrict event processing by start/end timestamps or recent time offsets.

  • Introduces TimeOption in cli.rs with new flags for --timeline-start, --timeline-end, and --time-offset
  • Implements filter_by_time in timefiler.rs and integrates it into aws_summary, aws_metrics, and aws_detect
  • Updates main.rs and module exports to wire the new filtering option through the existing commands

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
src/option/cli.rs Define new TimeOption struct and CLI flags
src/option/timefiler.rs Implement time parsing and filtering logic
src/option.rs Export the new timefiler module
src/main.rs Update calls to aws_metrics and aws_summary to use TimeOption
src/cmd/aws_summary.rs Apply filter_by_time before summary processing
src/cmd/aws_metrics.rs Apply filter_by_time before metrics processing
src/cmd/aws_detect.rs Apply filter_by_time in detection pipeline
Comments suppressed due to low confidence (2)

src/option/timefiler.rs:1

  • [nitpick] The module and file are named timefiler.rs, but the feature is a time filter. Consider renaming to timefilter.rs and the module to timefilter for clarity.
use crate::option::cli::TimeOption;

src/option/timefiler.rs:44

  • There’s no test case for invalid time_offset values (e.g., malformed strings). Add a test to ensure filter_by_time returns false when time_offset fails to parse.
fn parse_offset(offset: &str) -> Option<Duration> {

@Yamato-Security Yamato-Security deleted a comment from Copilot AI May 31, 2025
@Yamato-Security Yamato-Security deleted a comment from Copilot AI May 31, 2025
@Yamato-Security Yamato-Security deleted a comment from Copilot AI May 31, 2025
@fukusuket
Copy link
Collaborator Author

aws-ct-timeline --timeline-offset

./suzaku aws-ct-timeline -d ../data/suzaku-sample-data-main --time-offset 1y -q
Start time: 2025/05/31 23:26
Version: 0.3.0-dev (Dev Build)

Total detection rules: 66
Total log files: 3980
Total file size: 251.1 MiB

Scanning now. Please wait.

2024-08-18 13:01:07 · Attempt To Stop CloudTrail Logging · Zach Mathis (@yamatosecurity) · med · StopLogging · cloudtrail.amazonaws.com · us-east-1 · 109.196.12.142 · aws-cli/2.17.32 md/awscrt#0.21.2 ua/2.0 os/linux#5.10.16.3-microsoft-standard-WSL2 md/arch#x86_64 lang/python#3.11.9 md/pyimpl#CPython exec-env/grimoire_2a7fe1db-2f9c-4cde-a8b6-2bab508a589e cfg/retry-mode#standard md/installer#exe md/distrib#ubuntu.24 md/prompt#off md/command#cloudtrail.stop-logging · TrailDiscover · IAMUser · 192374575148 · arn:aws:iam::192374575148:user/TrailDiscover · AIDASZSTLCAWCAFWFS22H · AKIASZSTLCAWF4CPBKMF · de53d94e-f8b3-4111-b2d2-4f1c2f77a2b1 · 21a06b91-4860-4d2c-96fb-5c5c6374e3b2

2024-08-18 13:03:18 · Attempt To Modify CloudTrail Log Settings · Zach Mathis (@yamatosecurity) · med · UpdateTrail · cloudtrail.amazonaws.com · us-east-1 · 109.196.12.142 · aws-cli/2.17.32 md/awscrt#0.21.2 ua/2.0 os/linux#5.10.16.3-microsoft-standard-WSL2 md/arch#x86_64 lang/python#3.11.9 md/pyimpl#CPython exec-env/grimoire_00ac3026-f0fc-4124-8922-daacefee4eb4 cfg/retry-mode#standard md/installer#exe md/distrib#ubuntu.24 md/prompt#off md/command#cloudtrail.update-trail · TrailDiscover · IAMUser · 192374575148 · arn:aws:iam::192374575148:user/TrailDiscover · AIDASZSTLCAWCAFWFS22H · AKIASZSTLCAWF4CPBKMF · 8c76d32c-4419-48f7-bf99-21a7feddfeea · 0f11648b-4759-4491-9ff0-e61a28010bfd

2024-08-18 13:05:25 · Attempt To Delete A CloudTrail Log · Zach Mathis (@yamatosecurity) · med · DeleteTrail · cloudtrail.amazonaws.com · us-east-1 · 109.196.12.142 · aws-cli/2.17.32 md/awscrt#0.21.2 ua/2.0 os/linux#5.10.16.3-microsoft-standard-WSL2 md/arch#x86_64 lang/python#3.11.9 md/pyimpl#CPython exec-env/grimoire_a228e0aa-7f18-44ed-8df9-fcee3003a5d3 cfg/retry-mode#standard md/installer#exe md/distrib#ubuntu.24 md/prompt#off md/command#cloudtrail.delete-trail · TrailDiscover · IAMUser · 192374575148 · arn:aws:iam::192374575148:user/TrailDiscover · AIDASZSTLCAWCAFWFS22H · AKIASZSTLCAWF4CPBKMF · 03383b06-8e2e-4272-a022-5871c25e46f9 · b6f02c52-1158-4d31-98a8-a4751718f3db


Detection Frequency Timeline could not be displayed as there needs to be more than 5 events.

Rule Authors:
╭─────────────────────────────────╮
│ Zach Mathis (@yamatosecu... (3) │
╰─────────────────────────────────╯

Results Summary:
Events with hits / Total events: 3 / 4 (Data reduction: 1 events (25.00%))
Total | Unique critical detections: 0 (0%) | 0 (0%)
Total | Unique high detections: 0 (0%) | 0 (0%)
Total | Unique medium detections: 3 (100%) | 3 (100%)
Total | Unique low detections: 0 (0%) | 0 (0%)
Total | Unique informational detections: 0 (0%) | 0 (0%)

First event time: 2024-08-18 13:01:07 UTC
Last event time: 2024-08-18 13:05:25 UTC

Dates with most total detections:
critical: n/a, high: n/a, medium: 2024-08-18 (3), low: n/a, informational: n/a
╭──────────────────────────────────────────────────────────────────╮
│ Top critical alerts:                            Top high alerts: │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ n/a                                             n/a              │
│ n/a                                             n/a              │
│ n/a                                             n/a              │
│ n/a                                             n/a              │
│ n/a                                             n/a              │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Top medium alerts:                              Top low alerts:  │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Attempt To Stop CloudTrail Logging (1)          n/a              │
│ Attempt To Delete A CloudTrail Log (1)          n/a              │
│ Attempt To Modify CloudTrail Log Settings (1)   n/a              │
│ n/a                                             n/a              │
│ n/a                                             n/a              │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Top informational alerts:                                        │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ n/a                                                              │
│ n/a                                                              │
│ n/a                                                              │
│ n/a                                                              │
│ n/a                                                              │
╰───────────────────────────────────────────────╌──────────────────╯

Elapsed time: 00:00:06

Please report any issues with Suzaku rules to: https://github.com/Yamato-Security/suzaku-rules/issues
Please report any false positives with Sigma rules to: https://github.com/SigmaHQ/sigma/issues
Please submit new Sigma rules with pull requests to: https://github.com/SigmaHQ/sigma/pulls

@fukusuket
Copy link
Collaborator Author

aws-ct-summary --timeline-start


fukusuke@fukusukenoMacBook-Air suzaku-0.2.1-mac-aarch64 % ./suzaku aws-ct-summary -d ../data/suzaku-sample-data-main --timeline-start 2024-01-01T00:00:00Z -o sum.csv -q
Start time: 2025/05/31 23:28
Version: 0.3.0-dev (Dev Build)

Total log files: 3980
Total file size: 251.1 MiB

Scanning now. Please wait.

[00:00:06] 3,980 / 3,980   [========================================] 100%

Scanning finished.
                                                                                                                                                          Results saved: sum.csv (2.4 KiB)
Elapsed time: 00:00:06

fukusuke@fukusukenoMacBook-Air suzaku-0.2.1-mac-aarch64 % head sum.csv
UserARN,NumOfEvents,FirstTimestamp,LastTimestamp,AbusedAPIs-Success,AbusedAPIs-Failed,OtherAPIs-Success,OtherAPIs-Failed,AWS-Regions,SrcIPs,UserTypes,UserAccessKeyIDs,UserAgents
arn:aws:iam::192374575148:user/TrailDiscover,4,2024-08-18 12:59:16,2024-08-18 13:05:25,Unique APIs: 0,"Unique APIs: 3 | Total APIs 3
1 - UpdateTrail (cloudtrail.amazonaws.com) - Point logs to attacker-controlled S3 (2024-08-18 13:01:07 ~ 2024-08-18 13:03:18)
1 - StopLogging (cloudtrail.amazonaws.com) - Disable or delete CloudTrail logs (2024-08-18 13:01:07 ~ 2024-08-18 13:01:07)
1 - DeleteTrail (cloudtrail.amazonaws.com) - Disable or delete CloudTrail (2024-08-18 12:59:16 ~ 2024-08-18 13:05:25)","Unique APIs: 1 | Total APIs 1
1 - LookupEvents (cloudtrail.amazonaws.com) (2024-08-18 12:59:16 ~ 2024-08-18 13:03:18)",Unique APIs: 0,"Total regions: 1
4 - us-east-1 (2024-08-18 13:01:07 ~ 2024-08-18 13:01:07)","Total source IPs: 1
4 - 109.196.12.142 (2024-08-18 13:01:07 ~ 2024-08-18 13:01:07)",IAMUser,"Total access key IDs: 1
4 - AKIASZSTLCAWF4CPBKMF (2024-08-18 13:01:07 ~ 2024-08-18 13:01:07)","Total user agents: 4
1 - aws-cli/2.17.32 md/awscrt#0.21.2 ua/2.0 os/linux#5.10.16.3-microsoft-standard-WSL2 md/arch#x86_64 lang/python#3.11.9 md/pyimpl#CPython exec-env/grimoire_00ac3026-f0fc-4124-8922-daacefee4eb4 cfg/retry-mode#standard md/installer#exe md/distrib#ubuntu.24 md/prompt#off md/command#cloudtrail.update-trail (2024-08-18 13:01:07 ~ 2024-08-18 13:03:18)

@fukusuket
Copy link
Collaborator Author

aws-ct-metrics --timeline-end

 % ./suzaku aws-ct-metrics -d ../data/suzaku-sample-data-main --timeline-end 2019-01-01T00:00:00Z -o met.csv -q
Start time: 2025/05/31 23:29
Version: 0.3.0-dev (Dev Build)

Total log files: 3980
Total file size: 251.1 MiB

Scanning now. Please wait.

[00:00:07] 3,980 / 3,980   [========================================] 100%

Scanning finished.
                                                                                                                                                          Results saved: met.csv (20.0 KiB)
Elapsed time: 00:00:07

fukusuke@fukusukenoMacBook-Air suzaku-0.2.1-mac-aarch64 % head met.csv
EventName,Percent,Total
AssumeRole,21.20%,41910
DescribeSnapshots,12.81%,25332
GetBucketAcl,5.73%,11319
RunInstances,5.59%,11046
DescribeSpotPriceHistory,4.45%,8791
DescribeInstances,4.25%,8400
GetPolicyVersion,2.77%,5468
ListBuckets,2.41%,4772
ListEntitiesForPolicy,1.60%,3167

@YamatoSecurity YamatoSecurity self-requested a review June 6, 2025 00:38
Copy link
Contributor

@YamatoSecurity YamatoSecurity left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fukusuket LGTM! Thanks so much!

@YamatoSecurity YamatoSecurity merged commit 33233d9 into main Jun 6, 2025
4 checks passed
@YamatoSecurity YamatoSecurity deleted the 58-time-filter branch June 6, 2025 00:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

aws-ct-timeline time filtering
2 participants