Skip to content

Configuration

Awnexa reads its settings from config.json in the data directory (by default ./.awnexa, see Getting started). awnexa init creates the file; you can edit it by hand. Command-line options take precedence over the file, and unknown keys are rejected so that a typo does not go unnoticed.

{
"version": 1,
"profile": "readonly",
"regions": ["us-east-1", "ap-northeast-1"],
"network": {
"proxy": "http://proxy.example.com:8080",
"noProxy": [".internal.example.com"],
"caBundle": "corp-ca.pem"
}
}

AWS credentials are never stored here: Awnexa always uses the AWS SDK’s default credential chain (the same profiles, SSO sessions and environment variables as the AWS CLI).

Key Default Description
version 1 Format of the file
profile — AWS profile name (the name only)
sample — Set by awnexa init --sample: the directory holds the synthetic sample data. Do not set it yourself
regions — Regions to scan
reportLang en Language of report and snapshot diff --as markdown when --lang is not given (en or ja)
concurrency 4 Maximum parallel API listings (1–32)
maxAttempts 5 Attempts per AWS API call (1–10)
connectionTimeoutMs 10000 Connection timeout in milliseconds
requestTimeoutMs 60000 Request timeout in milliseconds
detailCallLimit 20000 Maximum per-resource detail calls per collector and region
evidence.enabled true Save the raw (sanitized) API responses
evidence.maxBytes 5242880 Maximum size of one evidence file
network.proxy — HTTP(S) proxy URL. Overrides HTTPS_PROXY / HTTP_PROXY
network.noProxy — Hosts reached without the proxy. Overrides NO_PROXY
network.caBundle — PEM file of extra trusted CA certificates. Relative to the data directory

Awnexa sends every request over HTTPS. Behind a proxy, set network.proxy, or rely on the same environment variables the AWS CLI uses:

Setting (first one found wins) Used for
network.proxy, then HTTPS_PROXY, then HTTP_PROXY The proxy
network.noProxy, then NO_PROXY Hosts reached directly
network.caBundle, then AWS_CA_BUNDLE Extra trusted certificates

Lower-case variable names (https_proxy, no_proxy) work too, and a variable without a scheme (proxy.example.com:8080) means http://. The proxy carries:

  • the AWS API calls of awnexa scan, including the sign-in calls that the AWS SDK makes for you (STS AssumeRole, IAM Identity Center / SSO);
  • usage statistics sent to the Awnexa backend (see Data sent).

Calls still go to the official AWS endpoints: the proxy only tunnels them (HTTP CONNECT), and TLS is end to end. The EC2 instance metadata service and the ECS credential endpoint are always reached directly.

http://proxy.example.com:8080
http://user:password@proxy.example.com:8080
https://proxy.example.com:8443

Use http:// for most corporate proxies (the connection to AWS is still TLS) and https:// only when the proxy itself accepts TLS. Basic authentication is supported; NTLM, Kerberos, SOCKS and PAC files are not.

If the user name or password contains @, :, /, % or #, percent-encode those characters (@ → %40, : → %3A, / → %2F, % → %25, # → %23). For example, the password p@ss:1 becomes http://alice:p%40ss%3A1@proxy.example.com:8080.

Each entry is one of:

Entry Matches
* Every host (the proxy is not used)
example.com, .example.com example.com and every host under it
10.0.0.1 That IP address
vpce.example.com:8443 That host on that port only

Address ranges (CIDR) are not supported. Use noProxy when some AWS endpoints are reached through VPC interface endpoints instead of the proxy.

If the proxy decrypts HTTPS traffic with its own certificate, Awnexa must trust that certificate, or every call fails with a certificate error (for example self-signed certificate in certificate chain). Point network.caBundle (or AWS_CA_BUNDLE) at a PEM file with the proxy’s CA certificate. It is added to the default trusted certificates, not used instead of them. Setting NODE_EXTRA_CA_CERTS before starting Awnexa also works.

Symptom What to check
AWS_AUTH_FAILED with (via proxy …) and a timeout or ECONNREFUSED The proxy host and port
ProxyAuthenticationRequired (HTTP 407) The proxy user name and password, and their percent-encoding
Certificate errors network.caBundle for a TLS-inspecting proxy
INVALID_PROXY The URL must start with http:// or https://
INVALID_CA_BUNDLE The file exists and contains -----BEGIN CERTIFICATE-----

The proxy may also refuse some AWS endpoints. Those services then appear in awnexa coverage as failed with the code NonAwsResponse (an HTTP error that did not come from AWS, not an IAM denial). Ask your network team to allow *.amazonaws.com and *.api.aws.