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.
Requirements
Section titled “Requirements”- 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)
1. Install
Section titled “1. Install”npm install -g awnexaawnexa versionThe 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++”).
Try it first without AWS
Section titled “Try it first without AWS”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:
awnexa init --sampleawnexa --data-dir ./.awnexa-sample status --compactawnexa --data-dir ./.awnexa-sample impact sg-0a1b2c3d4e5f60718 --depth 2 --compactTo 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:
claude mcp add awnexa-sample -- awnexa --data-dir "$PWD/.awnexa-sample" mcpWhen 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).
2. Set up AWS access
Section titled “2. Set up AWS access”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.
3. Create a data directory
Section titled “3. Create a data directory”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.
awnexa init --profile readonly --region us-east-1The 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.
4. Scan
Section titled “4. Scan”awnexa scanUse --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.
5. Check what was collected
Section titled “5. Check what was collected”awnexa statusawnexa coverage --status partial,failed,access_denied,unsupported,unknownstatus 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:
awnexa overviewawnexa resources list --type AWS::EC2::Subnet --limit 20 --format tableawnexa resources show <resource-id>awnexa impact <security-group-id> --depth 3Commands 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.
Next step
Section titled “Next step”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.