AWS

On this page

Before you start
Creating the IAM role
About the External ID
Connecting
How polling works
Events captured
How failed calls are treated
Disconnecting
Troubleshooting

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
Value	Used for
Governax AWS account id	The principal in your role's trust policy
External ID for this entity	A condition on the trust policy
The permissions policy to attach	The AWS-managed SecurityAudit policy

Creating the IAM role#

Open Integrations → AWS for the entity in Governax and keep it open: the connect page shows these same steps with this entity's trust policy filled in, and you paste the role ARN back there.

Start creating a role
IAM → Roles → Create role. A role, not a policy.
2
Paste the trust policy
For the trusted entity type choose Custom trust policy, replace the editor's contents with the trust policy from the connect page, and click Next. It looks like this, with your entity's values:
```
{
  "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>" }
    }
  }]
}
```
Choosing AWS account → Another AWS account, entering the Governax account id and ticking Require external ID produces the same policy.
3
Attach the SecurityAudit policy
Search for SecurityAudit, tick it and click Next.
```
arn:aws:iam::aws:policy/SecurityAudit
```
This is an AWS-managed, read-only policy. Governax cannot change anything in your account with it. Do not write a policy of your own.
Name the role and create it
For example GovernaxAudit. Then open the role and copy its ARN from the summary.

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
Check	Must	Proves
Assume the role without the External ID	Fail	The 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 CloudTrail	Succeed	The 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
Property	Value
Interval	Every 10 minutes
First poll	Backfills the previous 7 days
Each subsequent poll	Re-scans a 2-hour trailing window to absorb CloudTrail's delivery delay
Regions	Multi-region, discovered from your account
Filter	Write 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
Area	Event types
IAM lifecycle and privilege	`resource.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`. Policy attach and detach cover managed and inline policies and permissions boundaries (marked `inline` or `boundary` in the payload), and `resource.policy_changed` covers every policy version published, made default or deleted.
Credentials	`access.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-in	`security.root_login`, `security.login_failed`, `security.login_without_mfa`
Audit-trail tampering	`security.audit_logging_stopped`, `security.audit_trail_deleted`, `security.audit_trail_changed`
Storage exposure	`resource.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`
Defences	`security.threat_detection_disabled`, `security.threat_detection_changed`, `security.config_recording_disabled`, `security.kms_key_deletion_scheduled`, `security.kms_key_disabled`
Network exposure	`network.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 escape	`security.account_left_organization`, `security.account_removed_from_org`
Reconnaissance	`security.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
Class	Why it is kept
Console sign-in failures	Failed authentication is a signal in its own right.
Attempts to tamper with a security control	Someone trying and failing to disable CloudTrail or threat detection is worth recording. These are tagged as denied in the payload.
Authorisation denials against sensitive services	Recorded 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
Symptom	Cause and fix
Missing Resource / Unsupported Principal when saving	The trust policy was pasted into Policies → Create policy. It belongs in the role: Create role → Custom trust policy, or Trust relationships → Edit trust policy on an existing role.
The role can be assumed without the External ID	The condition is missing from the trust policy. Replace it with the one on the connect screen. This is a real security issue in your account, not a Governax quirk.
Governax could not assume the role	The trust policy is not the one on the connect screen (check the External ID matches exactly), or the role ARN is wrong.
The role cannot read CloudTrail	SecurityAudit is not attached. Role → Permissions → Add permissions → Attach policies.
Invalid role ARN	It must be a full role ARN including the 12-digit account id, not a role name.
Events from one region only	Region discovery needs the account's regions to be enabled and visible. Confirm CloudTrail is on in the regions you expect.
Nothing appears for 15 minutes	Expected. Up to 10 minutes of poll interval plus CloudTrail's own delivery delay.

General connector behaviour is covered in Connecting a tool.