OSIRIS JSON for Amazon AWS

[skhell]

The OSIRIS JSON producer for Amazon AWS is now available as v0.1.0. It collects over 60 resource types across all major AWS service categories like networking, compute, data services, storage, security, and identity, emitting a single portable topology document per region.

The challenge has never been a lack of AWS data, the modern challenge is that the architectural truth of an AWS environment is spread across accounts, regions, VPCs, subnets, security boundaries, managed services and service-specific APIs that are difficult to retrieve and translate in an end-to-end document report and topology view at a single point in time. The OSIRIS JSON producer for AWS turns that fragmented view into one portable topology document that can be validated, reviewed, diffed, and reused outside your AWS infrastructure.

What OSIRIS JSON producer for AWS v0.1.0 collects

The producer is organized around several collection phases that run per region. Global resources (Route53, CloudFront, Global Accelerator, IAM, OIDC, and SAML providers) are automatically merged into the us-east-1 document.

Category	Description
Networking	Extensive coverage of the full AWS network model: VPCs, subnets, security groups, route tables, network interfaces, internet gateways, NAT gateways, egress-only gateways, Elastic IPs, NACLs, VPC endpoints, VPC peering connections; Transit Gateways (attachments, route tables); Direct Connect (connections, gateways, virtual interfaces, LAGs); VPN connections and customer gateways; DHCP option sets, managed prefix lists, and flow logs.
Load Balancing & API	Covers ALB, NLB, GWLB, and Classic ELB (with target groups and listeners); API Gateway REST and HTTP/WebSocket APIs; CloudFront distributions.
DNS & Acceleration	Includes Route53 hosted zones, Resolver rules and endpoints, and Global Accelerator.
Compute	Covers EC2 instances, EKS clusters and node groups, ECS clusters and services, and Auto Scaling Groups.
Serverless & Messaging	Includes Lambda functions, SQS queues, Kinesis streams, and MSK clusters.
Managed Data Services	Covers RDS instances and Aurora clusters, DynamoDB tables, ElastiCache replication groups, DocumentDB, Neptune, Redshift, OpenSearch, and MemoryDB—each with their respective subnet groups where applicable.
Storage	Includes EBS volumes, S3 buckets, EFS file systems, and FSx file systems.
Security & Identity	Covers KMS customer-managed keys, Secrets Manager secrets, ECR repositories, WAFv2 Web ACLs, ACM certificates, RAM resource shares, IAM roles, instance profiles, and OIDC/SAML providers.
Observability & Events	Rounds out the picture with CloudWatch Log Groups, AWS Backup vaults, SNS topics, EventBridge event buses, and Step Functions state machines.

Your AWS infrastructure report and topology needs structure not just inventory

The OSIRIS JSON producer maps AWS resources directly to the OSIRIS JSON specification type taxonomy.

For example:

1. AWS EC2 instances become compute.vm
2. Lambda functions become compute.function.serverless
3. RDS and DynamoDB map to application.database
4. ElastiCache maps to application.cache
5. SQS queues become application.queue
6. Kinesis streams become application.eventstream
7. The core network model maps directly to network.vpc, network.subnet, network.security.group and so on.

Resources that have no direct OSIRIS JSON specification equivalent live in a dedicated AWS osiris.aws.* namespace following the OSIRIS JSON specification guidelines. This includes route tables, NAT gateways, Transit Gateway hierarchies, and service-specific constructs that are meaningful inside AWS but do not have a direct portable equivalent in the core spec.

Boundaries like VPCs, subnets, availability zones, and accounts are not secondary metadata—they are fundamental pillars of the AWS architecture itself. The OSIRIS JSON producer represents these boundaries through native groups, provider metadata, and explicit relationships without locking the document into AWS-only semantics.

Deep visibility without losing AWS-native meaning

The OSIRIS JSON producer preserves AWS-native details alongside the portable OSIRIS JSON model. Each resource carries provider metadata using CloudFormation type names (such as AWS::EC2::VPC or AWS::Lambda::Function) and the underlying aws-sdk-go-v2 source identifier.

When run with the --purpose audit flag, the producer emits full resource properties: instance types, private and public IPs, engine versions, storage sizes, backup retention settings, VPC configurations for Lambda, memory/timeout settings for functions, DynamoDB key schemas, and similar fields. In contrast, the default documentation mode strips these deep configuration properties before emission, preserving only the clean topology structure.

The special --include-raw-body flag (available in audit mode) attaches the full, raw AWS SDK response JSON for key resource types under extensions["osiris.aws.sdk"].body. This gives consumers the complete source record without losing the benefits of OSIRIS JSON normalization.

Topology became more than just a flat resource list

The OSIRIS JSON producer for AWS captures over 40 explicit connection types. The relationships between these components are what separate a true topology snapshot ready for draw.io or mermaidJS from a simple flat service inventory:

• VPCs contain subnets and route tables.
• Subnets attach to NAT gateways and availability zones.
• Security groups attach to network interfaces.
• Interfaces attach to instances.
• EBS volumes are contained by their instances.
• EKS clusters contain node groups, and ECS clusters contain services.
• RDS clusters contain their managed instances.
• Load balancers link directly to their target groups.
• Transit gateways connect to attachments and route tables.
• Direct Connect connections chain through gateways to virtual interfaces.

These connections represent the actual, living AWS architecture topology.

High quality documentation and topology matters even more in hybrid and multi-cloud designs

The AWS story becomes even more vital when your architecture does not stop at the cloud boundary.
The OSIRIS JSON examples already show AWS participating in both multi-hyperscaler and hybrid scenarios, demonstrating AWS resources tied logically to Microsoft Azure services. For Solution Architects this is a core use case that will become fully achievable with the OSIRIS JSON consumers (currently under development). You do not just want to know what exists inside AWS; you need to understand how AWS fits into your entire ecosystem for true end-to-end visibility.

This is where an open-source vendor-neutral format like OSIRIS JSON becomes genuinely useful, normalizing all provider/vendors language and format in one single portable JSON document.

An application tier in AWS, a database in Azure, or an on-premises dependency in a private data center connected via VPN should still be documented and viewed as a single, cohesive distributed architecture, not as disconnected list of service inventories.

The OSIRIS JSON producer contract

The AWS producer strictly follows the foundational OSIRIS JSON producer contract:

• Read-only: It never mutates or alters your infrastructure.
• No data invention: It does not invent unknown values.
• Deterministic: It generates identical output for the same source input.
• Secure by default: It strips secrets and fails safely when sensitive data is detected.
• Preserves native context: It retains AWS-native identifiers without replacing the core topology model.
• Fully validated: It validates cleanly through the canonical OSIRIS JSON CLI and validation engine.
• Zero overhead: It does not require an AI platform, MCP server, AI agents, SaaS intermediaries, or subscription APIs.
• Total control: Your infrastructure data stays entirely under your control, utilizing your personal or service account local API/credentials to connect to your infrastructure and retrieve information and generate the document.

Permission-denied errors from restricted IAM roles are handled gracefully—they are logged at the debug level and will not abort the collection run. Cross-account resources that are reachable by reference but outside the scope of the current profile are cleanly emitted as stubs with a cross-account state.

Operating modes

The OSIRIS JSON producer for AWS supports four execution modes: single-region, multi-region (covering 17 default AWS regions), CSV batch mode for multi-account pipelines and an interactive CLI picker when no flags are passed. AWS IAM Identity Center (SSO) authentication is handled smoothly through an OIDC device flow subcommand.

Read the related docs

• Download the OSIRIS JSON producer
• Read the OSIRIS JSON producer for AWS guidelines