Ontology¶

From docs/MCP_TOOLS.md on GitHub

cloudg builds an RDF/OWL ontology from a dataset (cloudg.graph.ontology.CloudOntology): one individual per asset (cmr:<asset id>), per finding (cmr:finding_<finding id>) and per tag (cmr:tag_<key>_<value>), typed with classes such as cm:RelationalDatabase, and connected by 64 relation types in seven groups (NETWORK, CONTAINMENT, IAM, DATA_FLOW, SECURITY, COMPUTE, GOVERNANCE). Data properties are cmp:hasName, hasARN, hasRegion, hasProvider, hasAccountId, hasCIDR, hasPort, hasProtocol, hasSeverity, hasRiskScore and isInternetExposed. The ontology is built on first use and cached; on a large map the first call can take a while and reports progress.

Prefixes predefined for SPARQL:

Prefix	Namespace	Holds
`cm:`	`https://cloudg.io/ontology#`	Classes.
`cmp:`	`https://cloudg.io/property/`	Relations and data properties.
`cmr:`	`https://cloudg.io/resource/`	Individuals.
`rdf:`, `rdfs:`, `owl:`, `xsd:`	The W3C namespaces

How the relations are read. cmp:FINDING_AFFECTS points at the asset a finding affects, resolved like an asset reference (id, ARN, unique name, unique ARN tail); only a finding whose resource matches nothing points at cmr: plus its raw resource_id. A CONTAINS edge gets a specific relation only when both endpoint types fit it (VPC_CONTAINS_SUBNET, SUBNET_CONTAINS_INSTANCE, CLUSTER_CONTAINS_SERVICE, ORG_CONTAINS_ACCOUNT), otherwise the generic CONTAINS. A security group or NACL rule yields INGRESS_ALLOWED or EGRESS_ALLOWED, INTERNET_REACHABLE for an internet source, and port relations read from the parsed port ranges (ALL_TRAFFIC, ONLY_SSH, ONLY_HTTP, ONLY_HTTPS, ONLY_RDP, PORT_RESTRICTED); PROTECTED_BY_SG and PROTECTED_BY_NACL come from ATTACHED_TO edges into a group (web-alb PROTECTED_BY_SG sg-web). ENCRYPTED_BY_KMS links an encrypted asset to its key.

`ontology_stats`¶

Category ontology · sensitivity internal · capabilities read_state · readOnly true, destructive false, idempotent true, openWorld false · outputSchema no · timeout: layer default (300 s)

Size and shape of the ontology: total_triples, classes_used, individuals, relation_type_counts (data properties included) and relation_group_counts, plus built_now, true when this call built it. Links cloudg://ontology/turtle.

Argument	Type	Default	Constraints	Description
`dataset`	string	`""`		Dataset name (see list_datasets). Empty = the active dataset.

Called with the arguments below, ontology_stats returned this structuredContent.

{}

{
  "dataset": "sample",
  "built_now": true,
  "total_triples": 1184,
  "classes_used": 30,
  "individuals": 78,
  "relation_type_counts": {
    "hasRiskScore": 12,
    "hasName": 57,
    "hasAccountId": 44,
    "isInternetExposed": 44,
    "INTERNET_REACHABLE": 7,
    "...": "36 more"
  },
  "relation_group_counts": {
    "NETWORK": 16,
    "CONTAINMENT": 15,
    "SECURITY": 38,
    "IAM": 12,
    "GOVERNANCE": 25,
    "COMPUTE": 11,
    "DATA_FLOW": 2
  }
}

The result also carried these resource links in content:

[
  {
    "type": "resource_link",
    "uri": "cloudg://ontology/turtle",
    "name": "ontology (turtle)",
    "mimeType": "text/turtle"
  }
]

A second call reads the cache and reports "built_now": false.

`sparql_query`¶

Category ontology · sensitivity restricted · capabilities read_state · readOnly true, destructive false, idempotent true, openWorld false · outputSchema yes · timeout 120 s

Runs one read-only SPARQL query against the dataset's ontology. Before parsing, string literals and comments are blanked and the query is rejected if it starts (after PREFIX / BASE declarations) with INSERT, DELETE, LOAD, CLEAR, DROP, CREATE, ADD, MOVE, COPY or WITH; both steps are linear scans, so a hostile query string cannot stall them. After parsing, FROM / FROM NAMED and any SERVICE clause are rejected, so a query can neither change the graph nor load remote data.

The tool is restricted. Its rows are keyed by the query's own variable names, so the privacy transforms cannot tell an identifier column from any other, and strict and the soc-analyst analyst do not see the tool.

Argument	Type	Default	Constraints	Description
`query`	string	required	min length 1; max length 20000	Read-only SPARQL (SELECT / ASK / CONSTRUCT / DESCRIBE). Predefined prefixes: cm: (classes, e.g. cm:RelationalDatabase), cmp: (relations / properties, e.g. cmp:INTERNET_REACHABLE, cmp:hasName), cmr: (individuals, cmr:), rdf:, rdfs:, owl:, xsd:. FROM, SERVICE and UPDATE are rejected.
`limit`	integer	`100`	1..1000	Row cap applied after the query runs.
`compact_uris`	boolean	`true`		Shorten URIs to prefix:name.
`dataset`	string	`""`		Dataset name (see list_datasets). Empty = the active dataset.

Result by query type (query_type is rdflib's algebra name):

`query_type`	Result
`SelectQuery`	`rows`: one object per solution, keyed by variable name. Values are strings (numbers too: `"12"`), URIs are compacted to `prefix:name` unless `compact_uris` is false, unbound variables are null.
`AskQuery`	`answer` (boolean), empty `rows`.
`ConstructQuery`, `DescribeQuery`	`rows` of `{subject, predicate, object}`.

limit is applied while reading the results, so a query whose patterns multiply out stops after limit rows instead of enumerating every combination; when more rows exist, truncated is true and a hint suggests LIMIT / OFFSET. Reading also stops after 60 seconds, with a hint to narrow the query. Clauses that need the whole solution set first (ORDER BY, aggregates, DISTINCT over a large set) and CONSTRUCT / DESCRIBE are bounded only by the tool's 120-second timeout. A SELECT result carries variable_kinds, which says whether each column holds URIs, literals or both (term).

The internet-reachable relation (the example in the tool's own description narrows it to relational databases, which returns no rows on the sample estate because nothing reaches the database directly):