Docs · Invictus-AWS
Invictus-AWS
Enumerate, configure and collect logs from an AWS account, then query CloudTrail with Athena.
Tool landing page: the Invictus-AWS tool overview.
On this page
- Start here
- What the tool is for
- Requirements
- Installation
- Authentication and permissions
- Configuration
- Core workflow
- Commands and operating modes
- Inputs and scope
- Outputs and directory structure
- Examples (from the repository)
- Operational cautions and limitations
- Troubleshooting (documented failure modes)
- Version and source information
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.
pip3 install -r requirements.txt
python3 invictus-aws.pyAuthentication and permissions
Configure your AWS credentials with the AWS CLI:
aws configureThis 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:*andglue:*on all resources (used by the analysis step), ands3:PutObject,s3:CreateBucket,s3:DeleteObject, ands3:DeleteBucketon resources matchingarn:aws:s3:::invictus-aws-*.
Operational note:ReadOnlyAccessplus the custom policy is what the repository documents. Theathena:*,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.
- Enumeration of activated AWS services and their details.
- Configuration retrieval for the activated services.
- Logs extraction for the activated services.
- 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:
python3 invictus-aws.pyPower-user form:
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. Defaultdefault.-w cloudor-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.-rand-Aare mutually exclusive.-s [step,step]: comma-separated list of steps.1enumeration,2configuration,3logs extraction,4logs analysis. Default is1,2,3. Step 4 is run alone.-start YYYY-MM-DDand-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. Formatbucket/subfolders/.-o bucket: bucket where query results are written. Formatbucket/[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.ddlfile 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 undercloudtrail-logs/). - The analysis step writes one CSV per query (
<query>-output.csv) and merges them intomerged_file.xlsx.
Examples (from the repository)
Collect from one region, skip the configuration step, write locally:
python3 invictus-aws.py -r eu-west-3 -s 1,3 -w localCollect from all regions starting with eu-west-3, default steps, results to S3:
python3 invictus-aws.py -A eu-west-3Analyze CloudTrail logs using the tool's default database and table:
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:
python3 invictus-aws.py -r eu-west-3 -w local -s 4 -x 7Operational 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
-startand-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/-Adoes not exist or is not enabled, the tool reports it and exits. Pass a valid, enabled region. - No region specified. If neither
-rnor-Ais 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.