OSIRIS JSON Producer for Amazon Web Services

The OSIRIS JSON AWS producer connects to Amazon Web Services via the AWS Go SDK v2 and generates OSIRIS JSON snapshots document of your account topology: VPCs, subnets, security groups, transit gateways, direct connect, load balancers, EC2 instances and more.

Prerequisites

1. Install the OSIRIS Producer see the How to Install page for more install options.
2. Configure AWS credentials using one of these methods:
   • aws configure --profile <name> for static credentials
   • aws configure sso for IAM Identity Center (SSO)
   • osirisjson-producer aws setup-sso --start-url <URL> for automated SSO setup
   • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
   • IAM instance profile (when running on EC2)
3. The authenticated user must have ReadOnly access to one or multiple target accounts. You can execute the producer on your local machine or invoke it using a scheduled job with a service account.

CLI usage

osirisjson-producer aws [flags]
osirisjson-producer aws setup-sso --start-url <URL> [--region <region>]
osirisjson-producer aws template --generate

SSO setup automates the profile creation

For organizations using AWS IAM Identity Center (formerly AWS SSO) with many accounts, the setup-sso subcommand automates profile creation:

osirisjson-producer aws setup-sso --start-url https://myorg.awsapps.com/start

This will:

1. Detect the SSO region automatically (or use --region to specify it)
2. Open a browser for device authorization
3. Discover all accounts and roles
4. Write profiles to ~/.aws/config as <AccountName>_<RoleName>
5. Cache the SSO token for immediate use (no separate aws sso login needed)

This is particularly useful for enterprises environment with hundreds of AWS accounts where manual profile configuration is impractical.

Interactive mode

Run without flags to get an interactive profile picker:

osirisjson-producer aws

The producer discovers all AWS CLI profiles from ~/.aws/config and ~/.aws/credentials, and presents a numbered list. Select using individual numbers (1,3,5), ranges (30-55), combinations (1,3,30-55), or type all. Then choose between all default regions (17 regions) or enter specific regions.

Single mode

Collect one account and region, saved as amazon-aws-<timestamp>-<name>-<region>.json:

osirisjson-producer aws --profile prod --region us-east-1

Multi-region mode

Collect all regions for an account. Creates a folder with one file per region:

# All 17 default regions
osirisjson-producer aws --profile prod --all-regions

# Specific regions
osirisjson-producer aws --profile prod --region us-east-1,eu-west-1

Batch mode (CSV)

Generate a CSV template:

osirisjson-producer aws template --generate

Collect from a CSV file:

osirisjson-producer aws -s accounts.csv -o ./output

The CSV template uses these columns:

Output hierarchy

Single region: saves to amazon-aws-<timestamp>-<name>-<region>.json in the current directory.

Multi-region (single account): creates a folder in the current directory:

amazon-aws-<timestamp>-<name>/
  us-east-1.json
  eu-west-1.json
  ...

Batch mode with output directory:

output/
  <AccountName>/
    <timestamp>/
      us-east-1.json
      eu-west-1.json
      ...

Each region produces a self-contained OSIRIS JSON document. Global resources (Route53 hosted zones, Global Accelerators) are merged into the us-east-1 document.

Flags reference

What it collects

The AWS producer collects all available data by default per the OSIRIS JSON specification - there is no detail level toggle. The following resource types are queried via the AWS SDK v2:

Standard OSIRIS types:

Custom types (osiris.aws.* namespace):

OSIRIS JSON output structure for AWS

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-aws",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["aws"],
      "accounts": ["123456789012"],
      "regions": ["us-east-1", "global"]
    }
  },
  "topology": {
    "resources": [ ... ],
    "connections": [ ... ],
    "groups": [ ... ]
  }
}

Resource types

Resource types follow the OSIRIS JSON v1.0 specification. Standard types are used where defined; AWS-specific types use the osiris.aws.* namespace.

Standard types:

• network.vpc - Virtual private clouds
• network.subnet - Subnets
• network.interface - Elastic network interfaces
• network.security.group - Security groups
• network.loadbalancer - Load balancers (ALB, NLB, GWLB, Classic)
• network.firewall - Network firewalls
• compute.vm - EC2 instances

Custom types (osiris.aws.*):

• osiris.aws.routetable - Route tables with route entries
• osiris.aws.gateway.internet - Internet gateways
• osiris.aws.gateway.nat - NAT gateways
• osiris.aws.gateway.vpn - VPN gateways
• osiris.aws.gateway.customer - Customer gateways
• osiris.aws.gateway.egressonly - Egress-only internet gateways
• osiris.aws.elasticip - Elastic IP addresses
• osiris.aws.vpc.endpoint - VPC endpoints (gateway and interface)
• osiris.aws.vpc.peering - VPC peering connections
• osiris.aws.transitgateway - Transit gateways
• osiris.aws.transitgateway.attachment - TGW attachments
• osiris.aws.transitgateway.routetable - TGW route tables
• osiris.aws.transitgateway.peering - TGW peering attachments
• osiris.aws.nacl - Network ACLs
• osiris.aws.directconnect - Direct Connect connections
• osiris.aws.directconnect.gateway - Direct Connect gateways
• osiris.aws.directconnect.vif - Direct Connect virtual interfaces
• osiris.aws.vpn.connection - VPN connections
• osiris.aws.dhcpoptions - DHCP option sets
• osiris.aws.prefixlist - Managed prefix lists
• osiris.aws.flowlog - VPC flow logs
• osiris.aws.availabilityzone - Availability zones
• osiris.aws.targetgroup - Target groups
• osiris.aws.resolver.rule - Route53 Resolver rules
• osiris.aws.resolver.endpoint - Route53 Resolver endpoints
• osiris.aws.route53.zone - Route53 hosted zones
• osiris.aws.globalaccelerator - Global Accelerators

Connection types

• contains - Containment (subnet inside VPC)
• network - Network connectivity (ENI-to-subnet, SG-to-ENI, NACL-to-subnet, route table associations, NAT gateway links, IGW/VGW attachments, VPC peerings, TGW attachments, Direct Connect VIF-to-gateway, VPN connections, DHCP-to-VPC, LB-to-target group)

Group types

• osiris.aws.account - Top-level account group, children are VPC groups
• network.vpc - VPC groups containing the VPC’s resources as members

Provider metadata

Every resource includes provider.type with the native AWS resource type (e.g. ec2:vpc, ec2:instance, elbv2:loadbalancer). Resources also include provider.region and provider.account.

Resource IDs

AWS resource IDs follow the pattern aws::arn:aws:<service>:<region>:<account>:<resource>, constructing canonical ARNs. For resources that already have ARNs (e.g. load balancers), the existing ARN is used with the aws:: prefix.

Examples

Single region

Collect a single AWS account and region:

osirisjson-producer aws --profile prod --region us-east-1

OSIRIS JSON output document (example):

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-aws",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["aws"],
      "accounts": ["123456789012"],
      "regions": ["us-east-1", "global"]
    }
  },
  "topology": {
    "resources": [
      {
        "id": "aws::arn:aws:ec2:us-east-1:123456789012:vpc/vpc-045dbb8300ce8bfd3",
        "type": "network.vpc",
        "name": "production-vpc",
        "status": "active",
        "provider": {
          "name": "aws",
          "native_id": "vpc-045dbb8300ce8bfd3",
          "type": "ec2:vpc",
          "region": "us-east-1",
          "account": "123456789012"
        },
        "properties": {
          "cidr_block": "10.0.0.0/16",
          "is_default": false,
          "owner_id": "123456789012"
        }
      },
      {
        "id": "aws::arn:aws:ec2:us-east-1:123456789012:instance/i-0abc123def456",
        "type": "compute.vm",
        "name": "web-server-01",
        "status": "active",
        "provider": {
          "name": "aws",
          "native_id": "i-0abc123def456",
          "type": "ec2:instance",
          "region": "us-east-1",
          "account": "123456789012"
        },
        "properties": {
          "instance_type": "c5.xlarge",
          "private_ip": "10.0.1.24",
          "public_ip": "203.0.113.10",
          "vpc_id": "vpc-123456789012",
          "subnet_id": "subnet-123456789012"
        }
      }
    ],
    "connections": [
      {
        "source": "aws::arn:aws:ec2:us-east-1:123456789012:subnet/subnet-0ed57794b6f7812a5",
        "target": "aws::arn:aws:ec2:us-east-1:123456789012:vpc/vpc-045dbb8300ce8bfd3",
        "type": "contains",
        "direction": "forward"
      }
    ],
    "groups": [
      {
        "id": "aws::account::123456789012",
        "type": "osiris.aws.account",
        "name": "Account 123456789012",
        "children": [
          "aws::vpc-group::us-east-1::vpc-123456789012"
        ]
      },
      {
        "id": "aws::vpc-group::us-east-1::vpc-123456789012",
        "type": "network.vpc",
        "name": "VPC production-vpc",
        "members": [
          "aws::arn:aws:ec2:us-east-1:123456789012:vpc/vpc-123456789012",
          "aws::arn:aws:ec2:us-east-1:123456789012:subnet/subnet-123456789012"
        ]
      }
    ]
  }
}