AWS Setup

LightPane connects to your AWS account using a cross-account IAM role. This is the same pattern used by Datadog, Wiz, Vanta, and every major cloud SaaS integration. LightPane never stores AWS credentials — it uses temporary STS credentials that expire automatically.

What gets created

A single IAM role in your AWS account with:

• Trust policy — allows the LightPane AWS account to assume the role
• AWS managed policy — SecurityAudit, covering read-only access to security and infrastructure configuration across 40+ services
• LightPane customer-managed policy — LightPaneAdditionalReadOnly, covering the Free Tier, Cost Explorer, Budgets, Savings Plans, account metadata, and CloudWatch metric retrieval APIs that live outside the SecurityAudit namespace. A first-class, named policy (not inline) so it's discoverable via iam:ListPolicies, IAM Access Analyzer, Config, and CSPM tooling
• External ID — a unique identifier derived from your LightPane user ID to prevent confused deputy attacks

The role can only read configuration, usage, and billing data. It cannot create, modify, or delete any resource in your account, and it cannot read the contents of your S3 objects, Secrets Manager secrets, or DynamoDB items.

Costs to be aware of

Reading your account is free for almost everything LightPane shows — configuration, inventory, Free Tier usage, and CloudWatch billing metrics all cost nothing to query. Two things are worth understanding:

• Cost Explorer is the one API AWS bills per call. The cost panes (Cost Summary, Cost Forecast, Cost by Tag) use GetCostAndUsage, which AWS charges at $0.01 per request. LightPane refreshes these only a few times a day (AWS itself only updates cost data every few hours), so the cost is typically a few cents a month — but it is the only place our reads add to your bill.
• Enabling security tooling is billed by AWS, not by LightPane. Security Hub, GuardDuty, AWS Config, and Inspector charge you for the service running — security checks performed, findings ingested, configuration items recorded, images scanned — whether or not LightPane is installed. If your bill shows Security Hub or GuardDuty charges, those come from having the service enabled in your account, not from LightPane reading it: our reads of those findings are free and do not change what AWS charges you. LightPane only displays findings that already exist. Enable or disable these services based on your own cost/benefit — the LightPane panes light up if the data is there and show a clear "not enabled" state if it isn't.

Everything else in the SecurityAudit + LightPaneAdditionalReadOnly policy is read-only configuration/usage data that AWS does not charge to query.

Setup with CloudFormation

The fastest way to create the role. LightPane publishes a CloudFormation template at:

https://lightpane.io/cloudformation/lightpane-reader-v2.yaml

and the accounts page drives a one-click flow that pre-fills it:

1. Log in to app.lightpane.io and open Cloud Accounts → AWS.
2. Pick a region in the Launch Stack card and click Launch Stack. The AWS CloudFormation console opens in a new tab with the template URL, the LightPane platform account ID, and your External ID all pre-filled.
3. Confirm and create the stack. It takes about a minute — when the status reads CREATE_COMPLETE, the role exists in your account as LightPaneReader.
4. Back on the LightPane accounts page, type your 12-digit AWS account ID (it's shown top-right in the AWS console, or as the AccountId output of the stack). LightPane constructs the role ARN from it automatically — you don't need to paste the full ARN.

That's it: name, account ID, region. LightPane has everything it needs.

The template creates this role:

AWSTemplateFormatVersion: '2010-09-09'
Description: LightPane read-only access role

Parameters:
  LightPaneAccountId:
    Type: String
    Description: LightPane platform AWS account ID
  ExternalId:
    Type: String
    Description: Unique External ID from your LightPane account

Resources:
  LightPaneReaderRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: LightPaneReader
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: !Sub 'arn:aws:iam::${LightPaneAccountId}:root'
            Action: 'sts:AssumeRole'
            Condition:
              StringEquals:
                'sts:ExternalId': !Ref ExternalId
      ManagedPolicyArns:
        - 'arn:aws:iam::aws:policy/SecurityAudit'
        - !Ref LightPaneAdditionalReadOnlyPolicy

  # Read-only extras SecurityAudit doesn't cover, as a customer-managed
  # policy (first-class, discoverable via iam:ListPolicies / Access
  # Analyzer / Config, versioned, uniform across accounts). The full
  # document — Free Tier, Cost Explorer, Budgets, Savings Plans, account
  # metadata, CloudWatch metrics, Compute Optimizer, Backup — is in the
  # published template: https://lightpane.io/cloudformation/lightpane-reader-v2.yaml
  LightPaneAdditionalReadOnlyPolicy:
    Type: AWS::IAM::ManagedPolicy
    Properties:
      ManagedPolicyName: LightPaneAdditionalReadOnly
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Sid: FreeTier
            Effect: Allow
            Action: ['freetier:GetFreeTierUsage']
            Resource: '*'
          # … remaining read-only statements omitted here for brevity —
          # see the published template linked above for the full document.

Outputs:
  RoleArn:
    Value: !GetAtt LightPaneReaderRole.Arn

Manual setup

If you prefer to create the role manually or via CLI:

# 1. Create the role with the trust policy
aws iam create-role \
  --role-name LightPaneReader \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::LIGHTPANE_ACCOUNT_ID:root"},
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID"
        }
      }
    }]
  }'

# 2. Attach the AWS managed SecurityAudit policy
aws iam attach-role-policy \
  --role-name LightPaneReader \
  --policy-arn arn:aws:iam::aws:policy/SecurityAudit

# 3. Create the customer-managed LightPaneAdditionalReadOnly policy for the
# additional permissions (Free Tier, Cost Explorer, Budgets, Savings Plans,
# account metadata, CloudWatch metric retrieval, Compute Optimizer, Backup)
# that aren't covered by SecurityAudit. Save the JSON below to
# lightpane-additional.json first. A customer-managed policy (rather than an
# inline one) is discoverable via iam:ListPolicies / Access Analyzer / Config.
aws iam create-policy \
  --policy-name LightPaneAdditionalReadOnly \
  --policy-document file://lightpane-additional.json

# 4. Attach that customer-managed policy to the role (swap in your account ID).
aws iam attach-role-policy \
  --role-name LightPaneReader \
  --policy-arn arn:aws:iam::YOUR_ACCOUNT_ID:policy/LightPaneAdditionalReadOnly

Contents of lightpane-additional.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "FreeTier",
      "Effect": "Allow",
      "Action": ["freetier:GetFreeTierUsage"],
      "Resource": "*"
    },
    {
      "Sid": "CostExplorer",
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostAndUsageWithResources",
        "ce:GetCostForecast",
        "ce:GetUsageForecast",
        "ce:GetDimensionValues",
        "ce:GetTags",
        "ce:GetCostCategories",
        "ce:ListCostCategoryDefinitions",
        "ce:GetRightsizingRecommendation",
        "ce:GetSavingsPlansUtilization",
        "ce:GetSavingsPlansCoverage",
        "ce:GetAnomalies",
        "ce:GetAnomalyMonitors",
        "ce:GetAnomalySubscriptions"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Budgets",
      "Effect": "Allow",
      "Action": [
        "budgets:ViewBudget",
        "budgets:DescribeBudgetAction",
        "budgets:DescribeBudgetActionsForAccount",
        "budgets:DescribeBudgetActionsForBudget"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SavingsPlans",
      "Effect": "Allow",
      "Action": [
        "savingsplans:DescribeSavingsPlans",
        "savingsplans:DescribeSavingsPlansOfferings",
        "savingsplans:ListTagsForResource"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AccountInfo",
      "Effect": "Allow",
      "Action": [
        "account:GetAccountInformation",
        "account:GetContactInformation",
        "account:ListRegions"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchMetrics",
      "Effect": "Allow",
      "Action": ["cloudwatch:GetMetricData"],
      "Resource": "*"
    }
  ]
}

Replace LIGHTPANE_ACCOUNT_ID and YOUR_EXTERNAL_ID with the values shown in your LightPane account.

Multi-account setup with StackSets

For AWS Organizations with many accounts, deploy the role across all accounts using CloudFormation StackSets:

1. Deploy the LightPane CloudFormation template as a StackSet from your management account
2. Target the entire Organization or specific OUs
3. Enable auto-deployment so new accounts added to the OU get the role automatically
4. Use a single External ID per Organization

StackSets support drift detection — if someone modifies the role, StackSets can detect and remediate the change.

Policies attached to the role

LightPane's role permissions come from two managed policies: the AWS-maintained SecurityAudit plus a small LightPane-specific customer-managed policy for the cost and billing namespaces that sit outside the standard AWS service APIs.

SecurityAudit (AWS managed)

arn:aws:iam::aws:policy/SecurityAudit grants read-only access to security and configuration data across 40+ services. It includes Get*, List*, and Describe* actions.

• Read-only — no create, update, or delete permissions
• Maintained by AWS — updated regularly as new services launch
• Used industry-wide — the standard policy for compliance and security tooling
• Does not include s3:GetObject — LightPane can list your buckets and their configuration but cannot read the contents of your files
• Does not include secretsmanager:GetSecretValue — LightPane can list your secrets but cannot read their values

LightPaneAdditionalReadOnly (customer-managed)

AWS doesn't ship a managed policy that covers the freetier:, ce:, budgets:, savingsplans:, account:, and cloudwatch:GetMetricData actions LightPane needs. These APIs sit outside the normal per-service Describe and List operations that SecurityAudit covers, so LightPane attaches a small customer-managed policy that explicitly enables the read-only calls it needs. Being a named, first-class policy (rather than inline), it shows up in iam:ListPolicies, IAM Access Analyzer, AWS Config, and any CSPM tooling that audits your estate:

Namespace	Purpose	What LightPane uses it for
freetier:GetFreeTierUsage	Free Tier month-to-date usage	Free Tier Usage pane
ce:Get*, ce:List*	Cost Explorer — spend, forecasts, anomalies, Savings Plans coverage	Upcoming cost panes
budgets:View*, budgets:Describe*	Budgets you've configured	Upcoming budget-tracking panes
savingsplans:Describe*, savingsplans:ListTagsForResource	Active Savings Plans	Upcoming reservation panes
account:Get*, account:ListRegions	Account contact metadata and opt-in regions	Account name display, region picker
cloudwatch:GetMetricData	Bulk metric retrieval for sparklines and aggregate values	lambda-radar, nat-traffic, cloudfront, asg-activity, step-functions, ecs-services panes

Like SecurityAudit, every action is a read — no namespace above includes Create, Update, or Delete.

Upgrading from v1

The v1 template used an inline policy named LightPaneCostAndBillingReadOnly and didn't include cloudwatch:GetMetricData. To upgrade an existing v1 stack, run an update-stack against the v2 template URL — CloudFormation replaces the inline policy with the customer-managed LightPaneAdditionalReadOnly policy and attaches it. No role re-creation or trust changes are needed.

Cost Explorer is a paid API

AWS charges about $0.01 per Cost Explorer call. LightPane's cache tier ensures we make at most one call per resource per 10 minutes on the free tier (and less often on higher tiers), keeping the expected cost well below a penny per user per day. See the tiering documentation for the full velocity table.

Billing APIs are us-east-1 only

The freetier:, ce:, and budgets: namespaces only exist in us-east-1 as regional endpoints, even though they represent data about your whole account. LightPane's discovery Lambda calls them against us-east-1 automatically regardless of which region your linked account defaults to.

The External ID

The External ID prevents confused deputy attacks. LightPane generates a unique ID for each cloud account you link. It is included as a condition in the role's trust policy, ensuring that only LightPane — with the correct External ID — can assume the role.

External ID is not a secret

The External ID is a unique identifier, not an authentication credential. It prevents one LightPane customer from tricking the platform into assuming another customer's role. It does not need to be kept confidential.

Supported regions

LightPane discovers resources in any AWS region. Specify the region in your service requests or access key configuration.

Common regions:

Region	Location
eu-west-1	Ireland
eu-west-2	London
eu-central-1	Frankfurt
us-east-1	N. Virginia
us-east-2	Ohio
us-west-2	Oregon
ap-southeast-1	Singapore
ap-northeast-1	Tokyo

Revoking access

Delete the IAM role in your AWS account at any time. LightPane immediately loses access. No action is needed on the LightPane side — the next discovery request will fail with an AccessDenied error, which LightPane handles gracefully.

Hiding or excluding individual resources

The SecurityAudit policy gives LightPane broad read access. If you want to keep specific resources out of LightPane without writing your own custom IAM policy, tag those resources with a lightpane-discovery tag.

Tag contract:

Tag value	Effect
no (or exclude)	Resource is never read into LightPane. The pane
response includes an excluded.count summary so you can see how many were
filtered, but no detail.
hidden (or count-only)	Resource detail is **never returned to the
browser**. The pane response includes a hidden.count summary so you can
audit how many are hidden.
anything else, or no tag	Resource is included normally.

Example — hide a specific S3 bucket from LightPane:

aws s3api put-bucket-tagging --bucket my-sensitive-bucket \
    --tagging 'TagSet=[{Key=lightpane-discovery,Value=hidden}]'

Example — fully exclude a Secrets Manager secret:

aws secretsmanager tag-resource \
    --secret-id arn:aws:secretsmanager:eu-west-1:111111111111:secret:legacy-imported-old-api-AbCdEf \
    --tags Key=lightpane-discovery,Value=no

Notes:

• The filter is applied per resource, with no inheritance. Tagging a VPC with no does not hide the EC2 instances inside it — each instance needs its own tag.
• Filtering applies to the source-of-truth pane only. If you exclude an EC2 instance, an Auto Scaling Group pane that simply counts members of an ASG will still include it in the count — there's no cascade through cross-service references.
• Resource types without tag support (some IAM access keys, some VPC sub-objects) cannot be filtered this way. The filter is a no-op for them.
• The filter operates alongside any per-key service scope you've set on a LightPane access key. Scope says "which service types this key can see"; the tag says "within those, which resources are visible".
• LightPane logs only counts by default — the ARNs of excluded or hidden resources are not written to LightPane's CloudWatch logs unless you opt your access key in to audit-mode (Business+ feature, not yet available).