cartography 0.93.0rc1__py3-none-any.whl → 0.123.0__py3-none-any.whl

cartography/models/ontology/mapping/__init__.py

@@ -0,0 +1,76 @@
+import logging
+
+from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.ontology.device import DeviceSchema
+from cartography.models.ontology.mapping.data.apikeys import APIKEYS_ONTOLOGY_MAPPING
+from cartography.models.ontology.mapping.data.computeinstance import (
+    COMPUTE_INSTANCE_ONTOLOGY_MAPPING,
+)
+from cartography.models.ontology.mapping.data.containers import (
+    CONTAINER_ONTOLOGY_MAPPING,
+)
+from cartography.models.ontology.mapping.data.databases import (
+    DATABASES_ONTOLOGY_MAPPING,
+)
+from cartography.models.ontology.mapping.data.devices import DEVICES_ONTOLOGY_MAPPING
+from cartography.models.ontology.mapping.data.thirdpartyapps import (
+    THIRDPARTYAPPS_ONTOLOGY_MAPPING,
+)
+from cartography.models.ontology.mapping.data.useraccounts import (
+    USERACCOUNTS_ONTOLOGY_MAPPING,
+)
+from cartography.models.ontology.mapping.data.users import USERS_ONTOLOGY_MAPPING
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+from cartography.models.ontology.user import UserSchema
+
+logger = logging.getLogger(__name__)
+
+
+# Following mapping are used to create ontology nodes and relationships from module nodes
+# They are leveraged in the ontology module to perform the actual mapping
+ONTOLOGY_NODES_MAPPING: dict[str, dict[str, OntologyMapping]] = {
+    "users": USERS_ONTOLOGY_MAPPING,
+    "devices": DEVICES_ONTOLOGY_MAPPING,
+}
+
+# Following mapping are used to normalize fields for semantic labels
+# They are leveraged directly by the load functions of each module at ingestion time
+SEMANTIC_LABELS_MAPPING: dict[str, dict[str, OntologyMapping]] = {
+    "useraccounts": USERACCOUNTS_ONTOLOGY_MAPPING,
+    "apikeys": APIKEYS_ONTOLOGY_MAPPING,
+    "computeinstance": COMPUTE_INSTANCE_ONTOLOGY_MAPPING,
+    "containers": CONTAINER_ONTOLOGY_MAPPING,
+    "databases": DATABASES_ONTOLOGY_MAPPING,
+    "thirdpartyapps": THIRDPARTYAPPS_ONTOLOGY_MAPPING,
+}
+
+ONTOLOGY_MODELS: dict[str, type[CartographyNodeSchema] | None] = {
+    "users": UserSchema,
+    "devices": DeviceSchema,
+}
+
+
+def get_semantic_label_mapping_from_node_schema(
+    node_schema: CartographyNodeSchema,
+) -> OntologyNodeMapping | None:
+    """Retrieve the OntologyNodeMapping for a given CartographyNodeSchema.
+
+    Args:
+        node_schema: An instance of CartographyNodeSchema representing the node.
+
+    Returns:
+        The corresponding OntologyNodeMapping if found, else None.
+    """
+    for module_name, module_mappings in SEMANTIC_LABELS_MAPPING.items():
+        if module_name == "ontology":
+            continue
+        for ontology_mapping in module_mappings.values():
+            for mapping_node in ontology_mapping.nodes:
+                if mapping_node.node_label == node_schema.label:
+                    logging.debug(
+                        "Found semantic label mapping for node label: %s",
+                        mapping_node.node_label,
+                    )
+                    return mapping_node
+    return None

cartography/models/ontology/mapping/data/apikeys.py

@@ -0,0 +1,93 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+# APIKey fields:
+# name
+# created_at
+# updated_at
+# expires_at
+# last_used_at
+
+anthropic_mapping = OntologyMapping(
+    module_name="anthropic",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="AnthropicApiKey",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="created_at"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="last_used_at", node_field="last_used_at"
+                ),
+            ],
+        ),
+    ],
+)
+
+openai_mapping = OntologyMapping(
+    module_name="openai",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="OpenAIApiKey",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="created_at"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="last_used_at", node_field="last_used_at"
+                ),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="OpenAIAdminApiKey",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="created_at"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="last_used_at", node_field="last_used_at"
+                ),
+            ],
+        ),
+    ],
+)
+
+scaleway_mapping = OntologyMapping(
+    module_name="scaleway",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="ScalewayApiKey",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="description", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="created_at"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="updated_at", node_field="updated_at"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="expires_at", node_field="expires_at"
+                ),
+            ],
+        ),
+    ],
+)
+
+APIKEYS_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "anthropic": anthropic_mapping,
+    "openai": openai_mapping,
+    "scaleway": scaleway_mapping,
+}

cartography/models/ontology/mapping/data/computeinstance.py

@@ -0,0 +1,95 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+aws_mapping = OntologyMapping(
+    module_name="aws",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="EC2Instance",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="id", node_field="id", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="instanceid", required=True
+                ),
+                OntologyFieldMapping(ontology_field="region", node_field="region"),
+                OntologyFieldMapping(
+                    ontology_field="public_ip_address", node_field="publicipaddress"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="private_ip_address", node_field="privateipaddress"
+                ),
+                OntologyFieldMapping(ontology_field="state", node_field="state"),
+                OntologyFieldMapping(ontology_field="type", node_field="instancetype"),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="launchtime"
+                ),
+            ],
+        ),
+    ],
+)
+
+scaleway_mapping = OntologyMapping(
+    module_name="scaleway",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="ScalewayInstance",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="id", node_field="id", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="region", node_field="zone"),
+                OntologyFieldMapping(
+                    ontology_field="private_ip_address", node_field="private_ip"
+                ),
+                OntologyFieldMapping(ontology_field="state", node_field="state"),
+                OntologyFieldMapping(
+                    ontology_field="type", node_field="commercial_type"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="creation_date"
+                ),
+            ],
+        ),
+    ],
+)
+
+digitalocean_mapping = OntologyMapping(
+    module_name="digitalocean",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="DODroplet",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="id", node_field="id", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="region", node_field="region"),
+                OntologyFieldMapping(
+                    ontology_field="public_ip_address", node_field="ip_address"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="private_ip_address", node_field="private_ip_address"
+                ),
+                OntologyFieldMapping(ontology_field="state", node_field="status"),
+                OntologyFieldMapping(ontology_field="type", node_field="size"),
+                OntologyFieldMapping(
+                    ontology_field="created_at", node_field="created_at"
+                ),
+            ],
+        ),
+    ],
+)
+
+COMPUTE_INSTANCE_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "aws": aws_mapping,
+    "scaleway": scaleway_mapping,
+    "digitalocean": digitalocean_mapping,
+}

cartography/models/ontology/mapping/data/containers.py

@@ -0,0 +1,88 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+aws_ecs_container_mapping = OntologyMapping(
+    module_name="aws",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="ECSContainer",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="id", node_field="arn", required=True
+                ),
+                OntologyFieldMapping(ontology_field="name", node_field="name"),
+                OntologyFieldMapping(ontology_field="image", node_field="image"),
+                OntologyFieldMapping(
+                    ontology_field="image_digest", node_field="image_digest"
+                ),
+                OntologyFieldMapping(ontology_field="state", node_field="last_status"),
+                OntologyFieldMapping(ontology_field="cpu", node_field="cpu"),
+                OntologyFieldMapping(ontology_field="memory", node_field="memory"),
+                OntologyFieldMapping(ontology_field="region", node_field="region"),
+                # namespace: Not applicable for ECS containers (AWS does not use namespaces)
+                OntologyFieldMapping(
+                    ontology_field="health_status", node_field="health_status"
+                ),
+            ],
+        ),
+    ],
+)
+
+kubernetes_mapping = OntologyMapping(
+    module_name="kubernetes",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="KubernetesContainer",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="id", node_field="id", required=True
+                ),
+                OntologyFieldMapping(ontology_field="name", node_field="name"),
+                OntologyFieldMapping(ontology_field="image", node_field="image"),
+                OntologyFieldMapping(
+                    ontology_field="image_digest", node_field="status_image_sha"
+                ),
+                OntologyFieldMapping(ontology_field="state", node_field="status_state"),
+                # cpu: Not exposed as a direct field in KubernetesContainer node
+                # memory: Not exposed as a direct field in KubernetesContainer node
+                # region: Not exposed as a direct field in KubernetesContainer node
+                OntologyFieldMapping(
+                    ontology_field="namespace", node_field="namespace"
+                ),
+                # health_status: Kubernetes uses status_ready and status_started separately, not a unified health_status field
+            ],
+        ),
+    ],
+)
+
+azure_mapping = OntologyMapping(
+    module_name="azure",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="AzureContainerInstance",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="id", node_field="id", required=True
+                ),
+                OntologyFieldMapping(ontology_field="name", node_field="name"),
+                # image: Not exposed as a direct field in AzureContainerInstance node (image info is in nested container properties)
+                # image_digest: Not exposed as a direct field in AzureContainerInstance node
+                OntologyFieldMapping(
+                    ontology_field="state", node_field="provisioning_state"
+                ),
+                # cpu: Not exposed as a direct field in AzureContainerInstance node
+                # memory: Not exposed as a direct field in AzureContainerInstance node
+                OntologyFieldMapping(ontology_field="region", node_field="location"),
+                # namespace: Not applicable for Azure Container Instances (Azure does not use namespaces in this context)
+                # health_status: Not exposed as a direct field in AzureContainerInstance node
+            ],
+        ),
+    ],
+)
+
+CONTAINER_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "aws_ecs_container": aws_ecs_container_mapping,
+    "kubernetes": kubernetes_mapping,
+    "azure": azure_mapping,
+}

cartography/models/ontology/mapping/data/databases.py

@@ -0,0 +1,182 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+# Database fields:
+# _ont_db_name - The name/identifier of the database
+# _ont_db_type - The database engine/type (e.g., "mysql", "postgres", "dynamodb")
+# _ont_db_version - The database engine version
+# _ont_db_endpoint - The connection endpoint/address for the database
+# _ont_db_port - The port number the database listens on
+# _ont_db_encrypted - Whether the database storage is encrypted
+# _ont_db_location - The physical location/region of the database
+
+aws_mapping = OntologyMapping(
+    module_name="aws",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="RDSCluster",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="database_name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="type", node_field="engine"),
+                OntologyFieldMapping(
+                    ontology_field="version", node_field="engine_version"
+                ),
+                OntologyFieldMapping(ontology_field="endpoint", node_field="endpoint"),
+                OntologyFieldMapping(ontology_field="port", node_field="port"),
+                OntologyFieldMapping(
+                    ontology_field="encrypted", node_field="storage_encrypted"
+                ),
+                OntologyFieldMapping(ontology_field="location", node_field="region"),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="RDSInstance",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="db_name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="type", node_field="engine"),
+                OntologyFieldMapping(
+                    ontology_field="version", node_field="engine_version"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="endpoint", node_field="endpoint_address"
+                ),
+                OntologyFieldMapping(ontology_field="port", node_field="endpoint_port"),
+                OntologyFieldMapping(
+                    ontology_field="encrypted", node_field="storage_encrypted"
+                ),
+                OntologyFieldMapping(ontology_field="location", node_field="region"),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="DynamoDBTable",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="type",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "dynamodb"},
+                ),
+                # _ont_db_version: Not applicable to DynamoDB (managed service)
+                # _ont_db_endpoint: DynamoDB uses AWS SDK endpoints, not direct DB endpoints
+                # _ont_db_port: Not applicable to DynamoDB (HTTPS API)
+                # _ont_db_encrypted: Not exposed in current model
+                OntologyFieldMapping(ontology_field="location", node_field="region"),
+            ],
+        ),
+    ],
+)
+
+azure_mapping = OntologyMapping(
+    module_name="azure",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="AzureSQLDatabase",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="type", node_field="kind"),
+                # _ont_db_version: Not directly exposed in AzureSQLDatabase model
+                # _ont_db_endpoint: Constructed from server endpoint, not directly on database
+                # _ont_db_port: Typically 1433 for Azure SQL, but not in model
+                # _ont_db_encrypted: Not directly exposed in current model
+                OntologyFieldMapping(ontology_field="location", node_field="location"),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="AzureCosmosDBSqlDatabase",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="type",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "cosmosdb-sql"},
+                ),
+                # _ont_db_version: Not applicable to managed CosmosDB
+                # _ont_db_endpoint: Account-level, not database-level
+                # _ont_db_port: Account-level, not database-level
+                # _ont_db_encrypted: Account-level configuration
+                OntologyFieldMapping(ontology_field="location", node_field="location"),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="AzureCosmosDBMongoDBDatabase",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="type",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "cosmosdb-mongodb"},
+                ),
+                # _ont_db_version: Not applicable to managed CosmosDB
+                # _ont_db_endpoint: Account-level, not database-level
+                # _ont_db_port: Account-level, not database-level
+                # _ont_db_encrypted: Account-level configuration
+                OntologyFieldMapping(ontology_field="location", node_field="location"),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="AzureCosmosDBCassandraKeyspace",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="type",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "cosmosdb-cassandra"},
+                ),
+                # _ont_db_version: Not applicable to managed CosmosDB
+                # _ont_db_endpoint: Account-level, not keyspace-level
+                # _ont_db_port: Account-level, not keyspace-level
+                # _ont_db_encrypted: Account-level configuration
+                OntologyFieldMapping(ontology_field="location", node_field="location"),
+            ],
+        ),
+    ],
+)
+
+gcp_mapping = OntologyMapping(
+    module_name="gcp",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="GCPBigtableInstance",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="name", node_field="display_name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="type",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "bigtable"},
+                ),
+                # _ont_db_version: Not applicable to managed Bigtable service
+                # _ont_db_endpoint: Constructed programmatically, not in model
+                # _ont_db_port: Not applicable (uses gRPC, not a fixed port)
+                # _ont_db_encrypted: Bigtable is encrypted at rest by default, not exposed
+            ],
+        ),
+    ],
+)
+
+DATABASES_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "aws": aws_mapping,
+    "azure": azure_mapping,
+    "gcp": gcp_mapping,
+}