Skip to content

Getting started

From installation to your first answer from Claude Code, you install Awnexa, set up AWS access, create a data directory and scan, then connect Claude Code. After that, see everyday use for keeping the data up to date.

  • Node.js 22.12 or later
  • Windows 11, macOS or Linux
  • AWS credentials that the AWS CLI can use (a profile, IAM Identity Center, aws login, environment variables or an instance role). Awnexa hands them to the AWS SDK and never stores them.
  • Claude Code, to ask about your system in plain words (the CLI also works on its own)
Terminal window
npm install -g awnexa
awnexa version

The package is awnexa on npm, where you can see the latest version and the versions released so far.

-g puts the awnexa command on your PATH. Claude Code runs the same command for the MCP server and the Skills, so install it globally rather than into a project.

Awnexa uses better-sqlite3, which ships prebuilt binaries for the major operating systems and Node.js versions. On other platforms npm builds it, which needs Python and a C++ compiler (on Windows, “Desktop development with C++”).

awnexa init --sample creates a separate data directory (./.awnexa-sample) with two scans of a made-up system, the one in the use cases. It makes no AWS call and reads no credentials, and its outputs say sample: true. Point Awnexa at it with --data-dir:

Terminal window
awnexa init --sample
awnexa --data-dir ./.awnexa-sample status --compact
awnexa --data-dir ./.awnexa-sample impact sg-0a1b2c3d4e5f60718 --depth 2 --compact

To use it from Claude Code, register the sample as its own MCP server (the output of awnexa init --sample ends with this command, with the full path filled in), then start Claude Code in the same directory and ask about the sample system:

Terminal window
claude mcp add awnexa-sample -- awnexa --data-dir "$PWD/.awnexa-sample" mcp

When you are ready, remove it with claude mcp remove awnexa-sample and continue below with your own account (it goes into ./.awnexa, not the sample directory).

Awnexa only needs permission to read. Attach the AWS managed policy ReadOnlyAccess to the role or user you scan with. That one policy is enough: it allows no changes to AWS, and Awnexa itself only calls the read-only APIs listed by awnexa plugins.

ReadOnlyAccess also allows reading data that Awnexa never reads (S3 objects, secret values, log events, …). If the same credentials are used by other tools, or you want to limit what a leaked credential could read, add this inline policy to the same role. It only takes those data reads away and does not affect Awnexa.

Optional: deny data reads
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyDataReads",
"Effect": "Deny",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion",
"s3express:CreateSession",
"secretsmanager:GetSecretValue",
"secretsmanager:BatchGetSecretValue",
"ssm:GetParameter",
"ssm:GetParameters",
"ssm:GetParametersByPath",
"ssm:GetParameterHistory",
"kms:Decrypt",
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:PartiQLSelect",
"dynamodb:GetRecords",
"logs:GetLogEvents",
"logs:FilterLogEvents",
"logs:GetLogRecord",
"logs:StartQuery",
"logs:GetQueryResults",
"logs:StartLiveTail",
"lambda:GetFunction",
"lambda:GetLayerVersion",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"rds:DownloadDBLogFilePortion",
"rds:DownloadCompleteDBLogFile",
"sqs:ReceiveMessage",
"kinesis:GetRecords",
"athena:GetQueryResults",
"cloudfront-keyvaluestore:GetKey",
"cloudfront-keyvaluestore:ListKeys"
],
"Resource": "*"
},
{
"Sid": "DenyApiKeyValues",
"Effect": "Deny",
"Action": "apigateway:GET",
"Resource": "arn:aws:apigateway:*::/apikeys*"
}
]
}

If something still shows up as access_denied in awnexa coverage (AWS sometimes adds a new action to ReadOnlyAccess later than the API itself), allow that action, which is listed under requiredIamActions in the output of awnexa plugins.

Make sure the AWS CLI can use the profile before you scan, for example with aws sts get-caller-identity --profile readonly.

Run this in the directory where you want to keep the scan results, such as your infrastructure repository. It creates ./.awnexa with a settings file (config.json) and a database (awnexa.db). Replace readonly with the name of your AWS CLI profile.

Terminal window
awnexa init --profile readonly --region us-east-1

The profile name and regions are saved as defaults, so later commands need no options. Only the profile name is stored, never credentials. To change them, run awnexa init again with --profile or --region; the other settings are kept. The output lists the commands to run next (next), and has a warning when no region is saved and the profile has no default region.

Commands find the data directory in this order: --data-dir, the AWNEXA_HOME environment variable, the nearest ./.awnexa (in this directory or a parent), then ~/.awnexa.

Terminal window
awnexa scan

Use --region for other regions (repeat it or separate with commas), or --all-regions for every region enabled for the account.

The command exits with 0 when everything was collected, and 4 when some services could not be read (for example, because of missing permissions). Everything that was read is still saved.

Terminal window
awnexa status
awnexa coverage --status partial,failed,access_denied,unsupported,unknown

status shows the scans and counts. coverage with these statuses lists only what could not be fully read. To fill the gaps, grant the missing permissions and scan again.

Then look around:

Terminal window
awnexa overview
awnexa resources list --type AWS::EC2::Subnet --limit 20 --format table
awnexa resources show <resource-id>
awnexa impact <security-group-id> --depth 3

Commands print JSON by default, for Claude Code and scripts. Listing commands such as resources list, coverage and snapshot list also take --format table, which is easier to read in a terminal. All commands and options are listed in the CLI reference.

Connect Awnexa to Claude Code so you can ask about your system in plain words. To learn what coverage, evidence and confidence mean, read how it works.