Connect to AWS

Nullstone provisions and manages infrastructure directly in your AWS account, so it needs credentials with access to that account. Nullstone supports two authentication methods:

Method	How it works	Best for
Assume Role (recommended)	You create an IAM role that trusts a dedicated Nullstone AWS account, secured with a unique External ID. Nullstone assumes the role for temporary credentials — no long-lived secrets are stored.	Almost everyone.
Access Keys	You create an IAM user, generate an access key, and give the key to Nullstone.	Environments where cross-account roles are not permitted.

AWS and Nullstone both recommend Assume Role — it avoids sharing long-lived credentials and can be revoked at any time by deleting the role.

Assume Role

In the Assume Role pattern, an admin creates an IAM role in the target AWS account that grants access to a single, dedicated Nullstone AWS account (Account ID: 875119311270). This account exists only to assume roles; our engineers do not have access to it. To strengthen the trust relationship, Nullstone generates a unique External ID for each provider that must be presented when assuming the role.

When you add an AWS provider in Nullstone, the UI generates a unique role name (nullstone-<random>) and External ID for you. You can complete setup automatically with CloudFormation (recommended) or manually with the CLI or AWS console.

TIP

For background from AWS, see How to use an external ID when granting access to your AWS resources to a third party.

Automated Setup

This is the default and fastest path — it launches a CloudFormation quick-create stack that provisions the role for you.

1. In the Nullstone UI, go to Providers, click Add Provider, and select AWS.
2. Leave the authentication method set to Assume Role (the default).
3. Enter your 12-digit AWS Account ID — the account you want Nullstone to manage.
4. Click Connect. Nullstone opens the AWS CloudFormation Quick create stack page in a new tab, pre-filled with the generated role name, External ID, and the Nullstone account.
5. Review the stack, acknowledge that it creates IAM resources, and click Create stack.
6. Return to the Nullstone tab. Nullstone automatically tests the connection and completes setup as soon as the role is available.

TIP

You must be signed in to the AWS console for the target account (in the same browser) for the quick-create link to open in the correct account.

Manual Setup

Prefer to create the role yourself? Use the role name and External ID shown in the Nullstone UI for your provider (the role name looks like nullstone-<random>). Switch the dialog to Manual Setup to reveal these values, then use either the CLI or the AWS console.

CLI

WARNING

To use the CLI, your terminal must be configured with access to the target AWS account. See Installing the AWS CLI and Configuring the AWS CLI.

Create a file assume-role-policy.json, inserting the External ID generated by the Nullstone UI:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::875119311270:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "(Insert the Nullstone-generated External ID)"
        }
      }
    }
  ]
}

Create the role using the role name from the Nullstone UI (replace nullstone-xxxxxxxx with your generated name):

aws iam create-role \
  --role-name nullstone-xxxxxxxx \
  --assume-role-policy-document file://assume-role-policy.json

Grant the role permission to provision infrastructure on your behalf:

aws iam attach-role-policy \
  --role-name nullstone-xxxxxxxx \
  --policy-arn arn:aws:iam::aws:policy/AdministratorAccess

FINISH

Return to the Nullstone UI and click Test Connection before proceeding.

AWS Console

Follow this link to begin creating a role for "An AWS account": https://console.aws.amazon.com/iam/home?region=us-east-1#/roles$new?step=type&roleType=crossAccount.

Set the Account ID to 875119311270. Check Require external ID and paste the External ID from the Nullstone UI. When done, click Next.

Attach the AdministratorAccess policy so the role can provision infrastructure on your behalf, then click Next.

On the review screen, enter the Role name shown in the Nullstone UI (nullstone-<random>). Click Create Role to finish.

FINISH

Return to the Nullstone UI and click Test Connection before proceeding.

Access Keys

If cross-account roles are not an option, you can connect an IAM user's access key instead.

1. In the AWS console, go to IAM → Users → Create user and give the user a name (for example, nullstone).
2. On the permissions step, choose Attach policies directly and select AdministratorAccess so Nullstone can provision infrastructure. Finish creating the user.
3. Open the new user, go to the Security credentials tab, and click Create access key. Choose Third-party service (or Application running outside AWS) as the use case.
4. Copy the Access Key ID and Secret Access Key. The secret is shown only once.
5. In the Nullstone UI, add an AWS provider, switch the authentication method to Access Keys, and enter the Access Key ID and Secret Access Key.
6. Click Test Connection to verify access.

WARNING

Access keys are long-lived credentials. Rotate them periodically, and remove the IAM user to revoke Nullstone's access.

Cost Provider

Nullstone can display cloud spend for a connected AWS account. Cost data is retrieved from the AWS Cost Explorer API using the same credentials you configured above (the assume-role or access-key provider) — there is no separate credential to manage.

Requirements

• Enable Cost Explorer in the AWS account. An account admin can enable it once from the AWS Billing and Cost Management → Cost Explorer console. It can take up to 24 hours for AWS to populate cost data after enabling.

• Grant ce:GetCostAndUsage to the connected role or user. This is the only Cost Explorer action Nullstone calls. If you attached AdministratorAccess during setup (above), this permission is already included. If you scoped the provider to a custom policy, add:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": "ce:GetCostAndUsage",
        "Resource": "*"
      }
    ]
  }

  Alternatively, attach the AWS managed policy AWSBillingReadOnlyAccess, which includes Cost Explorer read access.

Add the cost provider

1. In the Nullstone UI, go to Cloud Accounts and open the Cost tab.
2. Click Add Cost Provider.
3. Choose the AWS account you already connected as a provider, then confirm.
4. Nullstone runs an access test. When it passes, the account is marked Configured and cost data begins to appear.

If the access test fails, confirm that Cost Explorer is enabled and that the connected role or user has ce:GetCostAndUsage.

Included (linked) accounts

If the account you connect is the management (payer) account of an AWS Organization with consolidated billing, Cost Explorer returns spend for every member account under it. When Nullstone tests cost access, it discovers these linked accounts automatically and lists them as included accounts on the cost provider. To capture organization-wide spend, connect the payer account as your cost provider — you do not need to add each member account separately.

WARNING

The current (open) invoice month is an estimate — AWS revises it until the invoice finalizes. Nullstone reports unblended cost; amortized or blended views in the AWS console may differ from these figures.