Skip to content

cloudg inventory reference: return structures

From docs/INVENTORY_REFERENCE.md on GitHub

This document specifies every structure the inventory mapper returns or writes: the Python objects (CloudAsset, NetworkEdge, relation objects, InventoryResult, DependencyGraph results, OrganizationTopology, coverage records) and every exported file (inventory-map.json, inventory-graph.json, inventory-map.graphml, inventory-dependencies.json, inventory-organization.json, asset-map.json, compliance-map.json) plus the cloudg deps --json output. Each structure has a field table (name, type, nullability, meaning, how it is computed) and an annotated example.

Related documents:

  • INVENTORY_CATALOG.md: every asset type, the metadata keys it carries, the relations it declares, and the full relationship matrix.
  • INVENTORY_INTERNALS.md: how the mapper, collectors and linker work, and how to extend them.
  • DOCUMENTATION.md: CLI flags, configuration and the rest of cloudg.

The examples are taken from a real cloudg map --org run against a simulated (moto) AWS Organization with a management account, one member account in a nested OU, and one vendor account trusted by a role. Long values are shortened with …; UUIDs are real values from that run, so cross-references between the examples line up.

Sections

  • 1. Conventions

  • 2. Where each structure comes from

  • 3. CloudAsset

    cloudg.schema.models.CloudAsset, a Pydantic v2 model (extra="allow", populate_by_name=True). One node of the map: a cloud resource, an identity, a security...

  • 4. Identifier formats

    What can appear in arn, in metadata.aliases and as a relation target. The linker (INVENTORY_INTERNALS.md) resolves any of these.

  • 5. NetworkEdge

    cloudg.schema.models.NetworkEdge, a Pydantic v2 model (extra="allow"). A directed edge between two assets.

  • 6. Edge types and direction

    Direction always reads source verb target. The dependency column is how DependencyGraph turns the edge into a "dependent needs dependency" arrow...

  • 7. The relation object (metadata["relations"])

    Collectors never create edges between assets of different services directly. They declare what an asset talks to, by identifier, in metadata["relations"],...

  • 8. InventoryResult

    cloudg.inventory.InventoryResult (defined in cloudg/inventory/mapper_result.py, re-exported from cloudg.inventory.mapper and the package root). A dataclass.

  • 9. summary

    InventoryResult.summary, also the summary object of inventory-map.json.

  • 10. Coverage records

    cloudg.coverage.CollectionCoverage, one per collection unit. InventoryResult.coverage holds, in order: the discovery records (AWS organization, Azure...

  • 11. Unresolved references

    InventoryResult.unresolved_references and the unresolved_references arrays of inventory-map.json and inventory-dependencies.json. One entry per declared...

  • 12. DependencyGraph results

    cloudg.inventory.DependencyGraph(assets, edges, include_hierarchy=False). Every edge with a known dependency direction (section 6) whose endpoints are both...

  • 13. analysis() and inventory-dependencies.json

    InventoryResult.analysis(top=25) returns the dictionary that export() writes to inventory-dependencies.json. It uses a dependency graph built with...

  • 14. inventory-map.json

    The self-contained map. Written by export(), read by load() and cloudg deps.

  • 15. inventory-graph.json

    D3 force-layout data from GraphBuilder.to_d3_json(), built from the same assets and edges. Consumed by docs/viewer.html and any D3 / vis.js / Cytoscape...

  • 16. inventory-map.graphml

    The same graph as GraphML (NetworkX write_graphml_xml), for Gephi, yEd, Neo4j import or networkx.read_graphml.

  • 17. OrganizationTopology and inventory-organization.json

    cloudg.inventory.organization.OrganizationTopology, returned by discover_organization() and available as InventoryMapper.organization after a run....

  • 18. Organization assets on the map

    topology.to_assets() (organization_assets.topology_assets) adds these assets to the map (with aws.organization.map_structure, on by default). All are...

  • 19. asset-map.json and compliance-map.json

    Written by cloudg map --findings … or InventoryMapper.export_merged(result, findings, dir), which returns {"asset_map": Path, "compliance_map": Path}.

  • 20. cloudg deps --json

    cloudg deps loads a saved map (--map, default ./reports) and builds a dependency graph.

  • 21. Lower-level return values

    All inventory collectors implement the BaseCollector interface:

  • 22. Stability and compatibility

    What you can rely on across 0.6.x releases: