Search documentation

Find a documentation page by title, topic or keyword.

AWS

On this page

AWS is the most involved setup, because you create the access grant yourself: a cross-account IAM role that Governax can assume. Nothing is connected until that role exists.

Before you start#

You need permission to create IAM roles in the AWS account you want recorded, and CloudTrail should be enabled. Governax reads CloudTrail event history, which is on by default and retains 90 days.

The Governax connect screen shows three things you will need. Take them from there rather than from this page, because the External ID is specific to your entity:

Values shown on the connect screen
ValueUsed for
Governax AWS account idThe principal in your role's trust policy
External ID for this entityA condition on the trust policy
The permissions policy to attachThe AWS-managed SecurityAudit policy

Creating the IAM role#

  1. Open IAM, then Roles, then Create role

    Choose AWS account as the trusted entity type, then Another AWS account.

  2. Enter the Governax account id and require an External ID

    Tick the option to require an External ID and paste the one from the Governax connect screen. Alternatively paste the complete trust policy that screen provides, which looks like this:

    {
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<governax-account-id>:root" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "gvx-<your-entity-external-id>" }
    }
  }]
}

  3. Attach the SecurityAudit policy

    arn:aws:iam::aws:policy/SecurityAudit

    This is an AWS-managed, read-only policy. Governax cannot change anything in your account with it.

  4. Name the role and create it

    Then copy the role ARN.

About the External ID#

The External ID is generated by Governax, not chosen by you, and it is derived from your entity so that it exists before the connection does. It is AWS's standard protection against the confused deputy problem: without the condition, anyone who learned the Governax account id could ask Governax to assume a role in an account they do not own.

Connecting#

Paste the role ARN and connect. Governax runs two checks and both must pass:

Connect-time verification
CheckMustProves
Assume the role without the External IDFailThe condition is actually enforced, so the role is not open to anyone who knows the account id
Assume the role with the External ID, then read CloudTrailSucceedThe trust works and SecurityAudit is attached

A role that can be assumed without the External ID is rejected, even though it would technically work. That is deliberate: a misconfigured trust policy is a security problem in your account, and connecting anyway would hide it.

How polling works#

AWS polling behaviour
PropertyValue
IntervalEvery 10 minutes
First pollBackfills the previous 7 days
Each subsequent pollRe-scans a 2-hour trailing window to absorb CloudTrail's delivery delay
RegionsMulti-region, discovered from your account
FilterWrite events only

IAM, STS and root sign-in are global services recorded in one region, but S3, GuardDuty, Config, KMS and EC2 events are recorded where they happen. Governax discovers which regions your account has enabled and polls them, each tracking its own position, so activity outside your primary region is not missed.

Read-only API calls are excluded at the source. Every event the ledger records is a change, and including reads would bury them.

Events captured#

AWS event types by area
AreaEvent types
IAM lifecycle and privilegeresource.user_created, resource.user_deleted, resource.role_created, resource.role_deleted, resource.group_created, resource.group_deleted, access.policy_attached, access.policy_detached, access.group_member_added, access.group_member_removed, the three resource.policy_* events, security.trust_policy_changed
Credentialsaccess.api_token_created, access.api_token_revoked, security.password_changed, security.mfa_factor_added, security.mfa_factor_removed, security.password_policy_changed, security.password_policy_removed
Sign-insecurity.root_login, security.login_failed, security.login_without_mfa
Audit-trail tamperingsecurity.audit_logging_stopped, security.audit_trail_deleted, security.audit_trail_changed
Storage exposureresource.s3_bucket_policy_changed, resource.s3_bucket_policy_deleted, resource.s3_bucket_acl_changed, security.s3_public_access_block_removed, security.s3_public_access_block_changed
Defencessecurity.threat_detection_disabled, security.threat_detection_changed, security.config_recording_disabled, security.kms_key_deletion_scheduled, security.kms_key_disabled
Network exposurenetwork.security_group_rule_added, network.security_group_rule_removed, network.security_group_changed, network.nacl_changed, network.gateway_changed, network.route_table_changed, network.vpc_changed, network.vpc_peering_changed
Organisation escapesecurity.account_left_organization, security.account_removed_from_org
Reconnaissancesecurity.unauthorized_api_call

How failed calls are treated#

Most failed API calls are dropped, because a change that did not take effect is not a governance event. Three classes are kept:

Failed calls that are still recorded
ClassWhy it is kept
Console sign-in failuresFailed authentication is a signal in its own right.
Attempts to tamper with a security controlSomeone trying and failing to disable CloudTrail or threat detection is worth recording. These are tagged as denied in the payload.
Authorisation denials against sensitive servicesRecorded as security.unauthorized_api_call, which is the classic signature of credential probing.

Disconnecting#

Reconnecting later keeps the previous poll position, so a reconnect does not re-import everything.

Troubleshooting#

Common AWS connection problems
SymptomCause and fix
Role access check failedThe trust policy is wrong, the External ID does not match exactly, or SecurityAudit is not attached. Recheck each against the connect screen.
Rejected even though the role worksThe role can be assumed without the External ID, meaning the condition is missing from the trust policy. Add it. This is a real security issue in your account, not a Governax quirk.
Invalid role ARNIt must be a full role ARN including the 12-digit account id, not a role name.
Events from one region onlyRegion discovery needs the account's regions to be enabled and visible. Confirm CloudTrail is on in the regions you expect.
Nothing appears for 15 minutesExpected. Up to 10 minutes of poll interval plus CloudTrail's own delivery delay.

General connector behaviour is covered in Connecting a tool.