Before you can begin collecting data from an AWS account, you'll need toconfigure an account to use.

Once you're set up, you can run the ingestor, usingdefault options, with:awspx ingest

[root@localhost ~]#awspx ingest ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │                                 Create profile                                                 │ ├────────────────────────────────────────────────────────────────────────────────────────────────┤ │    AWS Access Key ID [None]:                     ***************E9UX5                          │ │    AWS Secret Access Key [None]:                 ***********************************Vukdh      │ │    Default region name [None]:                                                                 │ │    Default output format [None]:                                                               │ └────────────────────────────────────────────────────────────────────────────────────────────────┘                               Savedprofile 'default'      Identity: arn:aws:iam::000000000000:user/awspx                ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━Services: IAM, EC2, S3, LambdaDatabase: default.db      Account:  000000000000Region:   eu-west-1...

Next,explore this environment.

You'll need to setup an IAM identity for each AWS account you plan on ingesting:

1. Create an IAM user

2. Generate an access key

3. Attach the following built-in managed policies:

   • SecurityAudit (required)
   • ReadOnlyAccess (only if you want to ingest S3 Objects)

Touse a role instead, see the--envingestion option.

Theawspx command-line utility is a bash script (/usr/local/bin/awspx) that wrapscli.py: all commands are forwarded and executed within the context of theawspx docker container hosting Neo4j.

You can use the CLI to manage what is available from the web interface using ingestion, database, and supporting functions.

For a full list of command-line options run:awspx --help

The ingestor collects and processes AWS account data, expressing and storing it as a graph. This data includes resources and their relationships. Action information — expressed as Policies, or variants thereof — is automatically resolved; as are theattacks that incorporate them. For additional information on how it all works, and the thinking behind it, check outthis blog post.

Runawspx ingest --help for a full list of ingestion options.

Running the ingestor without any arguments will default to the following behavior:

• Theprofile will be set todefault (--profile default).
• Thedatabase will be set todefault.db (--db default.db)
• Allservices will be ingested
• Actions will automatically be resolved from Policy and ACL information (--skip-actions-all False)
• Attack paths are computed automatically (--skip-actions-all False --skip-attacks-all False).

1. Assuming the roleAudit, using the profileprd

   awspx ingest --profile prd --assume-role arn:aws:iam::000000000000:role/Audit --assume-role-duration 3600

2. Usingenvironment variables

   export AWS_ACCESS_KEY_ID="WY4XH9ZUFXVNIIG6C7JN"export AWS_SECRET_ACCESS_KEY="EDzukCRFBVDgq0//5yr01usTpHhniJHJ"export AWS_SESSION_TOKEN="keRJJBEWc3usCFS4I7wxq9MT6AYd7A53zN1bhvZ2ojHgfNZbmf5/////NWkyKutOZGw=="awspx ingest --env

3. SkippingALL S3 objects

    awspx ingest --skip-types AWS::S3::Object

4. Skipping the S3 Bucketslogs andpii (and all of their Objects)

     awspx ingest --skip-arns arn:aws:s3:::logs arn:aws:s3:::pii

5. Ingesting onlyIAM andEC2 resources, from the regioneu-west-2

   awspx ingest --services IAM EC2 --region eu-west-2

6. Skipping Policy/ACL resolution (attacks will be skipped implicitly)

   awspx ingest --skip-actions-all

• IAM
• EC2
• S3
• Lambda

SeeContributing for more information on how to extend this list.

Some services (e.g. IAM) are region independent, while others (e.g. EC2) are not. You can specify the target region using the--region option, or omit it to fallback to the value associated with theprofile. If neither value is set, awspx will default toeu-west-1.

For more information on supported regions, see the relevantAWS docs.

Credential profiles essentially wrapaws configure, allowing you to manage andstore credentials for those accounts you frequently interact with.

Runawspx profile --help for a full list of profile options:

1. Creating a profile calledprd (once completed, it will be available for ingestion, e.g.awspx ingest --profile prd)

   awspx profile --create prd

2. Deleting a profile calleddev

   awspx profile --delete dev

3. Listing all profiles

   awspx profile --list

Each database corresponds to a single.db file used by Neo4j and, by extension, awpsx's web interface. These files are created by the ingestor and named according to theprofile that was used at runtime.

Runawspx db --help for a full list of available options.

1. Listing all available databases

   awspx db --list

2. Switching the active database todev.db (you will need to refresh your browser)

   awspx db --use dev.db

3. Loading the sample databasesample.zip intosample.db

   awspx db --load-zip sample.zip

Before ingested data is written to a database, it is saved as a.zip file. This means historical data can be readily loaded without rerunning the ingestor.

To load a ZIP, saysample.zip included with awspx, you can executeawspx db --load-zip sample.zip, which will:

• Search/opt/awspx/data — or~/bin/awspx/data on macOS — forsample.zip
• Set the database tosample.db (based on the last field delimited by_ preceding.zip)
• Loadsample.zip intosample.db, overwriting any preexisting data.

ZIPs do no not include attack information.awspx attacks` must be run separately.

Attacks are the result of post-processing graph data to contextualize those actions that together constitute compromise. In graph terms, each new Attack that is discovered will translate to one or more new edges. Since this may give rise to additional attacks, this process is repeated until it converges, or the maximum number of iterations is reached. Attacks are automatically computed as part of the ingestion process unless explicitly excluded with--skip-attacks-all, or implicitly with--skip-actions-all.

Runawxpx attacks --help for a full list of available options.

1. Running through attacks at most once

   awspx attacks --max-attack-iterations 1

2. Setting the maximum search depth to 0 hops (i.e. directly available actions only)

   awspx attacks --max-attack-depth 0

3. Utilizing conditional actions as well (i.e. policies includingConditions orResource fields incorporating variables)

   awspx attacks --include-conditional-attacks

4. Skipping attacks involvingiam:CreatePolicyVersion

   awspx attacks --skip-attack CreatePolicyVersion

5. Searching for attacks that would directly enable adding a user to a group

   awspx attacks --only-attacks AddUserToGroup