Revoking GovIntel Access After Your Assessment

You do not have to do anything for GovIntel's access to end. This page explains what happens on its own, how to check what is in your account, and how to remove it yourself if you choose to. Read the two parts as separate things: expiry is automatic, cleanup is optional and is always yours to do.

Expiry is automatic. Cleanup is optional.

Two rules act on the expiry date. A condition on the role's trust policy refuses to start any new session after it, and a separate deny inside the role blocks every action after it, including a session started shortly before. An expired role still exists, but it can do nothing. See Expiry, revocation and re-authorization for how this is enforced.

What GovIntel does and does not do

GovIntel holds no permission to create, change or delete anything in your AWS account. The role it assumes is read-only, and it cannot remove itself, its stack or anything else. GovIntel therefore never deletes a stack, a role or an identity provider in your account, and nothing in this page is done for you.

One role per account, shared across engagements

There is one GovIntel assessment role in an AWS account, with a fixed name, GovIntel-Assessment-ReadOnly. A later assessment of the same account reuses that role, with a new expiry, rather than creating a second one. See If your account already has GovIntel access.

That has one consequence for cleanup: the role may be relied on by more than one engagement. A colleague, another team or a future reassessment may depend on it. Do not delete it on the assumption that it only served the assessment you have just read.

Let it expire instead of deleting it when any of these is true:

• You expect to reassess this account, or to commission another GovIntel assessment for it.
• Someone else in your organisation may have set up or used GovIntel access in this account.
• You are not certain who created the role or the stack.
• You cannot confirm the checks in the next section.

An expired role grants nothing, so leaving it costs you nothing in exposure.

Verify before you change anything

Every command here only reads. Run them with credentials for the AWS account in question. Stack commands look only at the region you give them, so use the region where the stack was created, and the same region throughout.

1. Look at the role and its tags.

aws iam get-role --role-name GovIntel-Assessment-ReadOnly \
  --query 'Role.{Created:CreateDate,Tags:Tags}'

A role set up by the GovIntel template carries the tag ManagedBy with the value GovIntel, and an ExpiresAt tag with its expiry.

2. Find out which CloudFormation stack, if any, owns it.

aws cloudformation describe-stack-resources --region <region> \
  --physical-resource-id GovIntel-Assessment-ReadOnly \
  --query 'StackResources[].[StackName,ResourceType,ResourceStatus]' --output table

If this finds nothing, that does not prove that no stack owns the role: the stack may be in another region. Look in the region where it was created. If you still cannot find exactly one owning stack, stop.

3. Check that the stack holds only the role.

aws cloudformation list-stack-resources --region <region> --stack-name <stack name from step 2> \
  --query 'StackResourceSummaries[].[ResourceType,LogicalResourceId,ResourceStatus]' --output table
aws cloudformation get-template-summary --region <region> --stack-name <stack name from step 2> \
  --query 'ResourceTypes'

For a stack created from the current GovIntel template, both show one resource and one type: AWS::IAM::Role. Anything else, in either list, means you must stop. In particular, a stack created from an earlier version of the template may also own an identity provider, and removing that stack would remove the provider with it.

4. Check the stack's state and parameters.

aws cloudformation describe-stacks --region <region> --stack-name <stack name from step 2> \
  --query 'Stacks[0].{Status:StackStatus,TerminationProtection:EnableTerminationProtection,ParameterKeys:Parameters[].ParameterKey}'

Expect a status of CREATE_COMPLETE or UPDATE_COMPLETE, and parameter names that include EngagementExpiresAt, GitHubOrganisation, GitHubRepository, GitHubRef and RoleName. Any other status, or parameters you do not recognise, means stop.

5. Check whether the role is being used. Every GovIntel session is named after its engagement and run, so you can see who assumed the role and when. See Auditing access in your CloudTrail.

What you found, and what to do

Optional cleanup when the assessment is permanently finished

Remove the stack only when every one of these is true:

1. You have finished with the report and do not expect another GovIntel assessment of this account.
2. No other engagement, team or person uses the role.
3. The role carries ManagedBy=GovIntel.
4. Exactly one stack owns the role, it contains only the role, and its status is CREATE_COMPLETE or UPDATE_COMPLETE.
5. You ran the checks above in the same account and region you are about to delete in, and repeated step 2 immediately before deleting.

Then delete that one stack, using the name exactly as step 2 printed it. CloudFormation removes the role and its attached policies with it, and nothing else, because the stack holds nothing else.

aws cloudformation delete-stack --region <region> --stack-name <stack name from step 2>
aws cloudformation wait stack-delete-complete --region <region> --stack-name <stack name from step 2>

Do not add options that keep resources or skip checks. If the deletion fails or reports DELETE_FAILED, stop and contact GovIntel rather than retrying. If termination protection is on, leave it on and contact GovIntel.

Confirm it is gone:

aws iam get-role --role-name GovIntel-Assessment-ReadOnly

A NoSuchEntity error means the role has been removed. Removing it means GovIntel can no longer assess the account until access is set up again.

If you would rather not remove anything, do nothing. The role will stay in your account, expired and unable to do anything.

What removing access does not affect

Removing the role or its stack does not remove or block a Board Pack you have already received.

• Your Board Pack. It is held in GovIntel's own storage and retrieved with GovIntel's own credentials. Retrieving it does not use the role in your account, and does not depend on the role, the stack or the connection state. How long it remains available is set by its own retention window, shown in the portal, and not by your access expiry or by removing the role. After that date a new pack means a new assessment. Download your copy and keep it with your board records.
• Evidence collected for the assessment. It is kept for a short, separate period set by GovIntel's retention schedule, and expires on that schedule whether or not the role exists.

What removal does change is the future: GovIntel cannot run another assessment against the account until access is set up again.

See Retention and availability and the Data retention schedule.

Never delete your GitHub identity provider

Your account may hold an identity provider for token.actions.githubusercontent.com. It belongs to your account and is shared by every GitHub Actions workflow you run, not only GovIntel's. The current GovIntel template does not create it, and its stack does not own it. An older template could have created it in some accounts, which is why step 3 must show the stack holding only the role. Do not delete the identity provider as part of removing GovIntel access. Deleting it would break your own deployments, and it is not needed to end GovIntel's access.

If something is unclear, stop

Stop and contact GovIntel before changing anything when:

• no stack owns the role, you cannot find it, or you find more than one;
• the tags or parameters are missing or are not what this page describes;
• the stack holds more than the role, or is in any state other than complete;
• the deletion fails;
• you cannot tell whether other engagements, teams or accounts rely on the role.

Reply to the email that delivered your Board Pack and describe what you found. Share the output of the read-only commands above. They contain no credentials.