Technical Guide: Generating Infrastructure Snapshots with OSIRIS JSON Producers

Practical Summary and Purpose

The OSIRIS JSON Producers are a suite of lightweight, read-only Go programs designed to provide end-to-end infrastructure visibility. By connecting directly to supported environments, these tools discover resources and their relationships, normalize vendor-specific data, and redact sensitive information. The result is a portable, vendor-neutral OSIRIS JSON document that represents the state of your infrastructure at a specific point in time. This approach eliminates the need for tribal knowledge, expensive consultancy, or reliance on closed, proprietary external platforms. The tool is intended for users who require local, controlled, and verifiable infrastructure data for documentation, audit reports, or integration into custom analytics and AI workflows.

The core philosophy of the OSIRIS JSON project is to ensure that infrastructure visibility remains under your full control. By generating a static, portable snapshot, you can perform various downstream tasks—such as CMDB updates, audit reporting, or feeding context-optimized data into AI agents—without exposing your live environment to external SaaS platforms or intermediary services. This methodology ensures that the data you collect is consistent, validated, and free from the risks associated with proprietary vendor lock-in or external data processing.

Prerequisites and Environment Control

To utilize OSIRIS JSON Producers, you must operate within an environment you fully control. The tools are designed to run locally on your workstation or server, ensuring that no AI platform, MCP server, or external agent is required for the discovery process. Because the producers are read-only, they do not modify your infrastructure. A critical security feature of the workflow is that credentials and authentication material are explicitly excluded from the generated document. This ensures that the resulting snapshot remains safe to store or share according to your own security policies. Users should consult the official installation guidelines at https://docs.osirisjson.org/osiris-producers/installation to prepare their local environment.

Before running a producer, ensure your workstation has the necessary network access to reach your target infrastructure provider. Since the tools are written in Go, they are designed to be portable and efficient. You must have the appropriate read-only permissions configured within your cloud or network environment to allow the producer to query resources. The tool does not require persistent agents or complex infrastructure changes, making it suitable for ad-hoc audits or scheduled snapshot generation as part of your standard operational procedures.

Documented Workflow and Architecture

The workflow follows a structured path from discovery to consumption. The producer connects to a vendor or platform, such as a hyperscaler or on-premises IT/OT environment, to discover resources. It then normalizes this data according to the OSIRIS JSON specification, which serves as the authoritative source of truth. During this phase, the tool performs redaction to protect sensitive values. The final output is a portable JSON document. This document can then be validated using the OSIRIS JSON Toolbox, which provides three-level validation. Once validated, the snapshot can be consumed by various tools to generate architecture documentation, audit reports, or topology updates. The following architecture workflow illustrates this process:

flowchart TD 
    subgraph VP ["Vendor / Platform"]
        A["Hyperscalers, Cloud & Hosting Providers"]
        B["On-Premises<br/>IT and OT"]
    end
    
    subgraph SP ["The OSIRIS JSON Specification"]
        S["The authoritative<br/>source of truth for the<br/>specification and core schema"]
    end
    
    subgraph PR ["The OSIRIS JSON Producers"]
        P["Discover, Normalize, Redact, Emit"]
        J["OSIRIS JSON Document<br/>Portable point-in-time infrastructure snapshot"]
    end
    
    subgraph VA ["The OSIRIS JSON Toolbox"]
        V["Validation toolbox<br/>Three-level validation"]
    end
    
    subgraph OC ["The OSIRIS JSON Consumers"]
        C["Consumers under development<br/>Read OSIRIS JSON documents"]
        AD["Architecture documentation reports"]
        AU["Audit reports"]
        DF["Snapshot diff view"]
        TP["Automatic topology<br/>generation and updates"]
    end
    
    subgraph UC ["Under Your Full Control"]
        U["One OSIRIS JSON file<br/>Multiple use cases"]
        M["CMDB / IPAM / DCIM workflows"]
        AI["AI platforms, agents<br/>and MCP servers"]
        X["Custom analytics<br/>and third-party tools"]
    end
    
    A -->|"Discovered by"| P
    B -->|"Discovered by"| P

    S -. "Defines the format" .-> J
    S -. "Guides implementation" .-> P

    P -->|"Generates"| J

    J -->|"Validated by"| V

    J -->|"Consumed by"| C
    C -->|"Generates"| AD
    C -->|"Generates"| AU
    C -->|"Generates"| DF
    C -->|"Generates"| TP

    J --> U
    U --> M
    U --> AI
    U --> X
    
    style VP fill:transparent,stroke:#555,stroke-width:1px,color:inherit
    style SP fill:transparent,stroke:#555,stroke-width:1px,color:inherit
    style PR fill:transparent,stroke:#4F7FE7,stroke-width:2px,color:inherit
    style VA fill:transparent,stroke:#555,stroke-width:1px,color:inherit
    style OC fill:transparent,stroke:#555,stroke-width:1px,color:inherit
    style UC fill:transparent,stroke:#555,stroke-width:1px,color:inherit

Supported Platforms and Limitations

The availability of producers varies by platform category. Currently, producers for Amazon AWS, Microsoft Azure, HPE Aruba Central, and Cisco are available for use. Other platforms, such as Google Cloud and Proxmox VE, are listed as under development, while Cloudflare support is planned. Users should verify the status of their specific infrastructure provider by visiting the official roadmap at https://osirisjson.org/en/commitments/roadmap. It is important to note that these tools are read-only and do not provide real-time monitoring or automated remediation. They are strictly for generating point-in-time snapshots. Users must ensure they have the necessary permissions within their respective cloud or network environments to allow the producer to perform discovery operations.

Furthermore, while the OSIRIS JSON document is a powerful tool for documentation and audit, it is not a replacement for active management systems. The producers are designed to capture the state of the infrastructure at the moment of execution. If your environment changes frequently, you may need to integrate the producer into a CI/CD pipeline or a scheduled task to maintain up-to-date snapshots. The tool's primary value lies in its ability to provide a consistent, vendor-neutral format that can be easily parsed by downstream consumers, regardless of the original source platform.