Docs · Invictus-AWS

Invictus-AWS

Enumerate, configure and collect logs from an AWS account, then query CloudTrail with Athena.

On this page

Start here 

Invictus-AWS is a Python script for acquiring data from an AWS account during an incident response engagement. It does not require installation beyond its Python dependencies. If you have been given access to an AWS environment and need to understand what is running, how it is configured, and what logs exist, run steps 1 through 3 to enumerate and collect, then run step 4 separately to query CloudTrail logs with Amazon Athena.

Tool landing page: the Invictus-AWS tool overview.

What the tool is for 

Invictus-AWS answers four questions about an AWS environment:

  • Which services are running in the account.
  • For each service, what the configuration details are.
  • What logging is available for each service that may be relevant to an investigation.
  • Whether there is activity of interest that can be found in the CloudTrail logs.

Requirements 

  • The AWS CLI. Install it following AWS instructions at https://aws.amazon.com/cli/.
  • Python 3 on the local system.
  • The Python packages listed in requirements.txt. Install them with:

pip3 install -r requirements.txt

  • An AWS account with permission to access the environment you are collecting from.

Installation 

There is no package install step for the tool itself. Clone or download the repository, install the Python requirements, and run invictus-aws.py directly.

Shell
pip3 install -r requirements.txt
python3 invictus-aws.py

Authentication and permissions 

Configure your AWS credentials with the AWS CLI:

Shell
aws configure

This requires the AWS Access Key ID for the account used to run the script.

The account running the script must hold two policies:

  • The AWS managed job-function policy ReadOnlyAccess.
  • The custom policy in source/files/policy.json.

The custom policy grants:

  • athena:* and glue:* on all resources (used by the analysis step), and
  • s3:PutObject, s3:CreateBucket, s3:DeleteObject, and s3:DeleteBucket on resources matching arn:aws:s3:::invictus-aws-*.

Operational note: ReadOnlyAccess plus the custom policy is what the repository documents. The athena:*, glue:*, and S3 create/delete grants are broader than read-only. Confirm with the owner whether a tighter minimum permission set is supported before describing this as least-privilege.

Configuration 

The analysis step uses a query file. By default this is source/files/queries.yaml. You can edit that file or supply your own with -f. Queries must be written in the form name-of-your-query: ... FROM DATABASE.TABLE ... without specifying the database and table, which the tool substitutes.

For a custom Athena table, an example data definition file is provided at source/files/example.ddl.

Core workflow 

The tool runs in four steps. Each step can be run independently; completing step 1 is not a precondition for step 2.

  1. Enumeration of activated AWS services and their details.
  2. Configuration retrieval for the activated services.
  3. Logs extraction for the activated services.
  4. Logs analysis of CloudTrail logs by running Athena queries. This step runs on its own.

By default the tool runs steps 1, 2, and 3. Step 4 is run separately with -s 4.

Commands and operating modes 

Run without arguments for walkthrough mode:

Shell
python3 invictus-aws.py

Power-user form:

Shell
python3 invictus-aws.py [-h] [-p profile] -w [{cloud,local}] (-r AWS_REGION | -A [ALL_REGIONS]) \
  -s [STEP] [-start YYYY-MM-DD] [-end YYYY-MM-DD] [-b SOURCE_BUCKET] [-o OUTPUT_BUCKET] \
  [-c CATALOG] [-d DATABASE] [-t TABLE] [-f QUERY_FILE] [-x TIMEFRAME]

Parameters:

  • -h, --help: print the help menu.
  • -p profile, --profile profile: AWS profile to use. Default default.
  • -w cloud or -w local: write results to an automatically created S3 bucket (cloud, the default) or to local storage (local).
  • -r region: analyze only the specified region.
  • -A [region]: analyze all enabled regions, optionally starting with the given region. -r and -A are mutually exclusive.
  • -s [step,step]: comma-separated list of steps. 1 enumeration, 2 configuration, 3 logs extraction, 4 logs analysis. Default is 1,2,3. Step 4 is run alone.
  • -start YYYY-MM-DD and -end YYYY-MM-DD: date range for CloudTrail log collection in step 3. Used together.
  • -b bucket: bucket containing the CloudTrail logs for step 4. Format bucket/subfolders/.
  • -o bucket: bucket where query results are written. Format bucket/[subfolders]/.
  • -c catalog: Athena catalog.
  • -d database: Athena database. Existing or new.
  • -t table: Athena table. An existing table, a new one with the default structure, or a .ddl file describing a new table.
  • -f file.yaml: a query file that already exists.
  • -x timeframe: a time filter appended to the default queries.

Inputs and scope 

  • Region scope is set by -r (one region) or -A (all enabled regions).
  • For step 4, the CloudTrail log source is set by -b, and must already exist in an S3 bucket.
  • Step 4 operates on CloudTrail logs only.

Outputs and directory structure 

  • With -w local, results are written under ./results/, organized by region.
  • With -w cloud, results are written to an automatically created S3 bucket.
  • Enumeration, configuration, and log results are written as JSON files per service (for example, region/logs/<service>.json, and per-event CloudTrail JSON files under cloudtrail-logs/).
  • The analysis step writes one CSV per query (<query>-output.csv) and merges them into merged_file.xlsx.

Examples (from the repository) 

Collect from one region, skip the configuration step, write locally:

Shell
python3 invictus-aws.py -r eu-west-3 -s 1,3 -w local

Collect from all regions starting with eu-west-3, default steps, results to S3:

Shell
python3 invictus-aws.py -A eu-west-3

Analyze CloudTrail logs using the tool's default database and table:

Shell
python3 invictus-aws.py -r eu-west-3 -s 4 -b bucket/path-to-the-existing-logs/ -o bucket/path-to-store-results/

Analyze CloudTrail logs, filter to the last 7 days, write results locally:

Shell
python3 invictus-aws.py -r eu-west-3 -w local -s 4 -x 7

Operational cautions and limitations 

  • The analysis step runs Amazon Athena and AWS Glue inside the target account. It creates and queries AWS resources and can incur cost. It is not a local-only operation.
  • CloudTrail log collection can be slow over wide date ranges. Bound it with -start and -end.
  • Step 4 requires CloudTrail logs already stored in an S3 bucket, in the default CloudTrail format (one JSON file per event, single line).
  • When the analysis step runs cloud-side, CloudTrail logs collected in step 3 may be written both locally and to an S3 bucket, because the analysis step needs the logs in a bucket.

Troubleshooting (documented failure modes) 

  • Expired security token. The tool reports that the security token in the request is expired and instructs the operator to set a new token before running. Re-authenticate with the AWS CLI.
  • Invalid or disabled region. If a region passed to -r/-A does not exist or is not enabled, the tool reports it and exits. Pass a valid, enabled region.
  • No region specified. If neither -r nor -A is supplied where required, the tool reports that a region option must be specified.
  • No CloudTrail logs found. In step 3, if no CloudTrail logs are found, the tool prints a notice to that effect.

Version and source information 

  • Repository: https://github.com/invictus-ir/Invictus-AWS
  • Branch: main
  • Commit: b4d080e61260bdff8a9d4b321bb5e957d6a11512
  • Retrieved: 2026-10-07
  • Releases: none published at retrieval.