AWS Collector

The AWS collector discovers and continuously monitors AWS infrastructure across compute, networking, storage, database, and serverless services. It connects to one or more AWS accounts and periodically scans all enabled regions, publishing configuration items and relationships for processing.

What Gets Discovered

The collector discovers 23 CI types across 11 AWS services:

Each resource's AWS Name tag is used as the CI name where available, falling back to the AWS resource ID (e.g., i-0abc123def456).

Prerequisites

• An AWS account with programmatic access
• An IAM user with an access key and secret key
• The IAM policy from the section below attached to that user

The collector only makes read-only API calls. No write permissions are needed or used.

IAM Policy

Create an IAM policy with the following JSON and attach it to the IAM user or role the collector will use. This is the minimum set of permissions required — no broader policies such as ReadOnlyAccess are needed.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ParascopeReadOnly",
            "Effect": "Allow",
            "Action": [
                "autoscaling:DescribeAutoScalingGroups",
                "autoscaling:DescribeLaunchConfigurations",
                "autoscaling:DescribeTags",
                "ec2:DescribeImages",
                "ec2:DescribeInstances",
                "ec2:DescribeRegions",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSnapshots",
                "ec2:DescribeSubnets",
                "ec2:DescribeVolumes",
                "ec2:DescribeVpcs",
                "ecs:DescribeClusters",
                "ecs:DescribeServices",
                "ecs:DescribeTaskDefinition",
                "ecs:ListClusters",
                "ecs:ListServices",
                "ecs:ListTaskDefinitions",
                "eks:DescribeCluster",
                "eks:ListClusters",
                "eks:ListTagsForResource",
                "elasticache:DescribeCacheClusters",
                "elasticache:DescribeCacheSubnetGroups",
                "elasticache:DescribeReplicationGroups",
                "elasticache:ListTagsForResource",
                "elasticloadbalancing:DescribeListeners",
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeTags",
                "elasticloadbalancing:DescribeTargetGroups",
                "elasticloadbalancing:DescribeTargetHealth",
                "iam:GetAccessKeyLastUsed",
                "iam:GetLoginProfile",
                "iam:GetPolicy",
                "iam:GetPolicyVersion",
                "iam:GetRole",
                "iam:GetUser",
                "iam:ListAccessKeys",
                "iam:ListAttachedRolePolicies",
                "iam:ListAttachedUserPolicies",
                "iam:ListGroupsForUser",
                "iam:ListInstanceProfilesForRole",
                "iam:ListMFADevices",
                "iam:ListPolicies",
                "iam:ListRolePolicies",
                "iam:ListRoles",
                "iam:ListUserPolicies",
                "iam:ListUsers",
                "lambda:GetFunction",
                "lambda:ListFunctions",
                "lambda:ListTags",
                "rds:DescribeDBClusters",
                "rds:DescribeDBInstances",
                "rds:DescribeDBSubnetGroups",
                "rds:ListTagsForResource",
                "s3:GetBucketEncryption",
                "s3:GetBucketLocation",
                "s3:GetBucketTagging",
                "s3:GetBucketVersioning",
                "s3:ListAllMyBuckets",
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ParascopeOrganizationsOptional",
            "Effect": "Allow",
            "Action": [
                "organizations:DescribeAccount",
                "organizations:ListAccounts"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ParascopeCostExplorerOptional",
            "Effect": "Allow",
            "Action": [
                "ce:GetCostAndUsage"
            ],
            "Resource": "*"
        }
    ]
}

The policy is split into three statements. If your account is not part of an AWS Organization, you can remove the ParascopeOrganizationsOptional statement entirely. The collector handles Organizations API access errors gracefully and falls back to sts:GetCallerIdentity for standalone accounts.

The ParascopeCostExplorerOptional statement enables daily cost enrichment. If you do not need per-resource cost data, remove this statement. Cost Explorer must be enabled at the account level (Billing console). See Cost Enrichment below.

Configuration

Each AWS account is configured as a separate Parascope source. Configure credentials and region filters for each source:

If neither region_allowlist nor region_denylist is set, the collector automatically discovers all regions enabled in your account and collects from all of them.

Multi-Account Setup

Each AWS account is its own source in Parascope. To monitor multiple accounts, add each as a separate source in the collector configuration.

Same-account collection uses the IAM user credentials directly. No role configuration needed.

Cross-account collection uses STS AssumeRole. A common pattern is a single IAM user in a management account that assumes a read-only role in each target account:

1. In each target account, create an IAM role (e.g., ParascopeCollectorRole) with the IAM policy above as its permissions policy. Add a trust policy that allows the management account's IAM user to assume it.

2. In each target account role's trust policy, optionally specify an aws:ExternalId condition for extra security.

3. In Parascope, configure one source per target account:

   • Set aws_access_key_id and aws_secret_access_key to the management account IAM user credentials
   • Set aws_role_arn to the target account role ARN (e.g., arn:aws:iam::123456789012:role/ParascopeCollectorRole)
   • Set aws_external_id if you configured one in the trust policy

Each source has independent health tracking and circuit breaking — a misconfigured or unreachable account does not block collection from other healthy accounts.

Collected Resources

EC2 Instances

Terminated EC2 instances are excluded. Only instances in pending, running, stopping, or stopped states are collected. Configuration tracked in change history includes instance type, state, VPC/subnet assignment, private and public IPs, attached security groups, AMI ID, availability zone, platform, and tags.

S3 Buckets

S3 buckets are collected globally (once per account, not per region). Each bucket's home region is recorded using GetBucketLocation. Configuration includes encryption status, versioning status, and tags.

EBS Snapshots and AMIs

Both are scoped to self-owned resources only. DescribeSnapshots and DescribeImages are called with OwnerIds=['self'] to avoid returning the millions of public AWS marketplace snapshots and images, which would create noise in your CMDB.

Security Groups

Full ingress and egress rule details are captured in config, including protocol, port ranges, CIDR ranges, and source security group references. Because security group rules define blast radius and compliance posture, changes to rules are tracked in change history.

Aurora Clusters

aws.rds_cluster captures Aurora clusters. Aurora member instances also appear as aws.rds_instance CIs and are linked to their cluster via contains relationships. Standalone RDS instances (non-Aurora) have no parent cluster.

IAM Users, Roles, and Policies

IAM resources are collected globally (once per account, not per region). Users include attached managed policies, group memberships, MFA device status, access key metadata (IDs and last-used dates, never secrets), and inline policy count. Roles include attached policies and instance profile associations. Service-linked roles (path /aws-service-role/) are excluded. Policies are customer-managed only (Scope=Local), including the default version document.

ECS Clusters and Services

Clusters track capacity providers, settings, and task/service counts. Services capture the active task definition, launch type, desired count, network configuration, load balancer bindings, and deployment status. Task definitions collect the latest active revision per family with container definitions, CPU/memory limits, network mode, and execution/task role ARNs.

EKS Clusters

Control plane metadata including Kubernetes version, platform version, VPC networking (subnets, security groups, public/private endpoint access), logging configuration, encryption settings, and the cluster IAM role. OIDC identity provider stored in raw data.

ElastiCache Clusters and Replication Groups

Replication groups are the operational unit for Redis/Valkey HA. Configuration includes engine, version, node type, shard topology (cluster mode, node groups, replicas per shard), automatic failover, Multi-AZ, encryption, and backup settings. Individual cache clusters are nodes within a replication group (Redis) or standalone resources (Memcached). Subnet group names are resolved to VPC subnet IDs.

Relationships

The collector maps the following relationships between AWS resources:

This gives you a navigable VPC topology: account → VPC → subnet → instances, plus security group coverage, EBS attachment chains, load balancer membership, IAM policy attachment graphs, ECS service lineage, EKS cluster networking, and ElastiCache replication topology.

Cross-source correlation also links AWS resources to other Parascope sources:

• aws.ec2_instance to kubernetes.node — matched by private IP or hostname, linking EC2 instances to EKS backing nodes
• aws.rds_instance to postgresql.server — matched by RDS endpoint hostname, when the PostgreSQL collector monitors the same database
• aws.eks_cluster to kubernetes.cluster — matched by cluster name

Cost Enrichment

The AWS collector integrates with AWS Cost Explorer to attach per-resource monthly cost estimates to your AWS CIs.

How It Works

Cost Explorer data is 12-24 hours behind real time, so cost enrichment runs once daily (default: 02:00 UTC) rather than during the collection cycle. The enricher queries Cost Explorer with per-resource granularity, matches resource ARNs to existing CIs, and creates cost allocation records.

Monthly cost is projected from month-to-date data: the daily average multiplied by days in the billing month. This produces a full-month estimate comparable to cost projections from other Parascope sources.

Supported Resources

Cost data is matched to these CI types by resource ARN:

Prerequisites

• The ParascopeCostExplorerOptional IAM policy statement (see IAM Policy above)
• Cost Explorer enabled at the AWS account level (Billing console, Account Settings)
• At least one full day of the current billing month elapsed

If Cost Explorer is not enabled, the enricher logs a warning and skips that source. CIs remain fully functional without cost data.

Troubleshooting

AccessDenied errors

The collector logs AccessDenied errors per API call. If you see these, the IAM user is missing a permission. Compare the error message's action against the IAM policy above and add the missing action. Common causes:

• A newer version of the collector added a new API call not in your existing policy
• The ParascopeOrganizationsOptional statement was removed but the account is part of an Organization

API throttling

AWS throttles API calls per account per region. The collector uses boto3's adaptive retry mode, which automatically backs off and retries throttled requests. You do not need to take action — throttled calls are retried automatically. If collection is frequently slow due to throttling on accounts with large resource counts, increase the collection interval.

Region not enabled

If you receive errors about a region not being enabled, that region requires opt-in activation in the AWS console under Account Settings. Either activate the region or add it to region_denylist to skip it.

InvalidClientTokenId

This error means the access key is wrong or has been deactivated. Check that aws_access_key_id and aws_secret_access_key match an active IAM user access key in the AWS console.

Organizations errors

If you see AccessDenied errors specifically from organizations:DescribeAccount or organizations:ListAccounts, the account is not in an AWS Organization or the IAM user lacks the Organizations permissions. This is not a problem — remove the ParascopeOrganizationsOptional statement from your IAM policy and the collector will fall back to sts:GetCallerIdentity for the account CI automatically.

Cost Explorer not enabled

If you see OptInRequired errors in the enrichment logs, Cost Explorer is not enabled for the AWS account. Enable it in the Billing console under Account Settings. Cost Explorer can take up to 24 hours to activate after opt-in. You can also remove the ParascopeCostExplorerOptional statement from the IAM policy to suppress the warnings.

Related Documentation

• Managing Collectors — Collector health and configuration
• Collector Reference: Infrastructure — Kubernetes, Proxmox, OpenStack, and Netbox
• Correlation Engine — Cross-source relationship discovery
• CI Types — Complete CI type reference