cartography 0.117.0__py3-none-any.whl → 0.119.0__py3-none-any.whl

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

@@ -0,0 +1,160 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+from cartography.models.ontology.mapping.specs import OntologyRelMapping
+
+bigfix_mapping = OntologyMapping(
+    module_name="bigfix",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="BigfixComputer",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="computername", required=True
+                ),
+                OntologyFieldMapping(ontology_field="os", node_field="os"),
+            ],
+        ),
+    ],
+)
+crowdstrike_mapping = OntologyMapping(
+    module_name="crowdstrike",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="CrowdstrikeHost",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="hostname", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="os_version", node_field="os_version"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="platform", node_field="platform_name"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="serial_number", node_field="serial_number"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="instance_id", node_field="instance_id"
+                ),
+            ],
+        ),
+    ],
+)
+duo_mapping = OntologyMapping(
+    module_name="duo",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="DuoEndpoint",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="device_name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="os", node_field="os_family"),
+                OntologyFieldMapping(
+                    ontology_field="os_version", node_field="os_version"
+                ),
+                OntologyFieldMapping(ontology_field="model", node_field="model"),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="DuoPhone",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="name", required=True
+                ),
+                OntologyFieldMapping(ontology_field="model", node_field="model"),
+                OntologyFieldMapping(ontology_field="platform", node_field="platform"),
+            ],
+        ),
+    ],
+    rels=[
+        OntologyRelMapping(
+            __comment__="Link Device to User based on DuoUser-DuoPhone relationship",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:DuoUser)-[:HAS_DUO_PHONE]-(:DuoPhone)<-[:OBSERVED_AS]-(d:Device) MERGE (u)-[r:OWNS]->(d) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        ),
+        OntologyRelMapping(
+            __comment__="Link Device to User based on DuoUser-DuoEndpoint relationship",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:DuoUser)-[:HAS_DUO_ENDPOINT]-(:DuoEndpoint)<-[:OBSERVED_AS]-(d:Device) MERGE (u)-[r:OWNS]->(d) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        ),
+    ],
+)
+kandji_mapping = OntologyMapping(
+    module_name="kandji",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="KandjiDevice",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="device_name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="serial_number", node_field="serial_number"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="os_version", node_field="os_version"
+                ),
+                OntologyFieldMapping(ontology_field="model", node_field="model"),
+                OntologyFieldMapping(ontology_field="platform", node_field="platform"),
+            ],
+        ),
+    ],
+)
+snipeit_mapping = OntologyMapping(
+    module_name="snipeit",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="SnipeitAsset",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="name", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="serial_number", node_field="serial"
+                ),
+                OntologyFieldMapping(ontology_field="model", node_field="model"),
+            ],
+        ),
+    ],
+    rels=[
+        OntologyRelMapping(
+            __comment__="Link Device to User based on SnipeitUser-SnipeitAsset relationship",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:SnipeitUser)-[:HAS_CHECKED_OUT]-(:SnipeitAsset)<-[:OBSERVED_AS]-(d:Device) MERGE (u)-[r:OWNS]->(d) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        )
+    ],
+)
+tailscale_mapping = OntologyMapping(
+    module_name="tailscale",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="TailscaleDevice",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="hostname", node_field="hostname", required=True
+                ),
+                OntologyFieldMapping(ontology_field="os", node_field="os"),
+            ],
+        ),
+    ],
+    rels=[
+        OntologyRelMapping(
+            __comment__="Link Device to User based on TailscaleUser-TailscaleDevice relationship",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:TailscaleUser)-[:OWNS]-(:TailscaleDevice)<-[:OBSERVED_AS]-(d:Device) MERGE (u)-[r:OWNS]->(d) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        )
+    ],
+)
+
+
+DEVICES_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "bigfix": bigfix_mapping,
+    "crowdstrike": crowdstrike_mapping,
+    "duo": duo_mapping,
+    "kandji": kandji_mapping,
+    "snipeit": snipeit_mapping,
+    "tailscale": tailscale_mapping,
+}

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

@@ -0,0 +1,239 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+anthropic_mapping = OntologyMapping(
+    module_name="anthropic",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="AnthropicUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="fullname", node_field="name"),
+            ],
+        ),
+    ],
+)
+
+airbyte_mapping = OntologyMapping(
+    module_name="airbyte",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="AirbyteUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="fullname", node_field="name"),
+            ],
+        ),
+    ],
+)
+
+cloudflare_mapping = OntologyMapping(
+    module_name="cloudflare",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="CloudflareMember",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="firstname"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="lastname"),
+            ],
+        ),
+    ],
+)
+
+duo_mapping = OntologyMapping(
+    module_name="duo",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="DuoUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="firstname"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="lastname"),
+                OntologyFieldMapping(ontology_field="username", node_field="username"),
+                OntologyFieldMapping(ontology_field="fullname", node_field="realname"),
+            ],
+        ),
+    ],
+)
+entra_mapping = OntologyMapping(
+    module_name="entra",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="EntraUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="given_name"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="surname"),
+                OntologyFieldMapping(
+                    ontology_field="fullname", node_field="display_name"
+                ),
+            ],
+        ),
+    ],
+)
+github_mapping = OntologyMapping(
+    module_name="github",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="GitHubUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="username", node_field="username"),
+                OntologyFieldMapping(ontology_field="fullname", node_field="fullname"),
+            ],
+        ),
+    ],
+)
+gsuite_mapping = OntologyMapping(
+    module_name="gsuite",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="GSuiteUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="given_name"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="lastname", node_field="family_name"
+                ),
+                OntologyFieldMapping(ontology_field="fullname", node_field="name"),
+            ],
+        ),
+    ],
+)
+keycloak_mapping = OntologyMapping(
+    module_name="keycloak",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="KeycloakUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="username", node_field="username"),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="first_name"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="last_name"),
+            ],
+        ),
+    ],
+)
+lastpass_mapping = OntologyMapping(
+    module_name="lastpass",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="LastpassUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="fullname", node_field="name"),
+            ],
+        ),
+    ],
+)
+openai_mapping = OntologyMapping(
+    module_name="openai",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="OpenAIUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="fullname", node_field="name"),
+            ],
+        ),
+    ],
+)
+scaleway_mapping = OntologyMapping(
+    module_name="scaleway",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="ScalewayUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="first_name", node_field="first_name"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="last_name", node_field="last_name"
+                ),
+                OntologyFieldMapping(ontology_field="username", node_field="username"),
+            ],
+        ),
+    ],
+)
+snipeit_mapping = OntologyMapping(
+    module_name="snipeit",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="SnipeitUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(ontology_field="username", node_field="username"),
+            ],
+        ),
+    ],
+)
+tailscale_mapping = OntologyMapping(
+    module_name="tailscale",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="TailscaleUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="fullname", node_field="display_name"
+                ),
+            ],
+        ),
+    ],
+)
+
+
+USERS_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "anthropic": anthropic_mapping,
+    "airbyte": airbyte_mapping,
+    "cloudflare": cloudflare_mapping,
+    "duo": duo_mapping,
+    "entra": entra_mapping,
+    "github": github_mapping,
+    "gsuite": gsuite_mapping,
+    "keycloak": keycloak_mapping,
+    "lastpass": lastpass_mapping,
+    "openai": openai_mapping,
+    "scaleway": scaleway_mapping,
+    "snipeit": snipeit_mapping,
+    "tailscale": tailscale_mapping,
+}

cartography/models/ontology/mapping/specs.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+from dataclasses import field
+
+
+@dataclass(frozen=True)
+class OntologyFieldMapping:
+    """Mapping between an ontology field and a module's node field.
+
+    Attributes:
+        ontology_field: The field name in the ontology.
+        node_field: The corresponding field name in the module's node.
+        required: Whether this field is required to create an ontology node or not.
+
+    Example:
+        OntologyFieldMapping(ontology_field="email", node_field="email_address", required=True)
+        This mapping indicates that the 'email' field in the ontology corresponds to the 'email_address' field in the module's node and is required.
+        So {"id": "123", "email_address": "<email_value>"} can be mapped to an ontology node, but {"id": "123"} cannot.
+    """
+
+    ontology_field: str
+    node_field: str
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class OntologyNodeMapping:
+    """Mapping for a node in the ontology.
+
+    Attributes:
+        node_label: The label of the ontology node.
+        fields: A list of OntologyFieldMapping defining the field mappings for this node.
+    """
+
+    node_label: str
+    fields: list[OntologyFieldMapping]
+
+
+@dataclass(frozen=True)
+class OntologyRelMapping:
+    """Mapping for a relationship in the ontology.
+
+    Attributes:
+        query: The query used to retrieve this relationship.
+        iterative: Whether this relationship requires batch processing (iterative) or can be created in a single query.
+        __comment__: An optional comment about this relationship.
+    """
+
+    query: str
+    iterative: bool = False
+    __comment__: str | None = None
+
+
+@dataclass(frozen=True)
+class OntologyMapping:
+    """Ontology mapping for a specific module.
+
+    Attributes:
+        module_name: The name of the module.
+        nodes: A list of OntologyNodeMapping defining the nodes for this module.
+        rels: A list of OntologyRelMapping defining the relationships for this module.
+    """
+
+    module_name: str
+    nodes: list[OntologyNodeMapping]
+    rels: list[OntologyRelMapping] = field(default_factory=list)

cartography/models/ontology/user.py

@@ -0,0 +1,52 @@
+# See https://d3fend.mitre.org/dao/artifact/d3f:User/
+from dataclasses import dataclass
+
+from cartography.models.core.common import PropertyRef
+from cartography.models.core.nodes import CartographyNodeProperties
+from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.nodes import ExtraNodeLabels
+from cartography.models.core.relationships import CartographyRelProperties
+from cartography.models.core.relationships import CartographyRelSchema
+from cartography.models.core.relationships import LinkDirection
+from cartography.models.core.relationships import make_target_node_matcher
+from cartography.models.core.relationships import OtherRelationships
+from cartography.models.core.relationships import TargetNodeMatcher
+
+
+@dataclass(frozen=True)
+class UserNodeProperties(CartographyNodeProperties):
+    id: PropertyRef = PropertyRef("email")
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+    email: PropertyRef = PropertyRef("email", extra_index=True)
+    username: PropertyRef = PropertyRef("username")
+    fullname: PropertyRef = PropertyRef("fullname")
+    firstname: PropertyRef = PropertyRef("firstname")
+    lastname: PropertyRef = PropertyRef("lastname")
+
+
+@dataclass(frozen=True)
+class UserToUserAccountRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+# (:User)-[:HAS_ACCOUNT]->(:UserAccount)
+# This is a relationship to a sementic label used by modules' users nodes
+class UserToUserAccountRel(CartographyRelSchema):
+    target_node_label: str = "UserAccount"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"email": PropertyRef("email")},
+    )
+    direction: LinkDirection = LinkDirection.OUTWARD
+    rel_label: str = "HAS_ACCOUNT"
+    properties: UserToUserAccountRelProperties = UserToUserAccountRelProperties()
+
+
+@dataclass(frozen=True)
+class UserSchema(CartographyNodeSchema):
+    label: str = "User"
+    extra_node_labels: ExtraNodeLabels = ExtraNodeLabels(["Ontology"])
+    properties: UserNodeProperties = UserNodeProperties()
+    scoped_cleanup: bool = False
+    other_relationships: OtherRelationships = OtherRelationships(
+        rels=[UserToUserAccountRel()],
+    )

cartography/models/openai/user.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from cartography.models.core.common import PropertyRef
 from cartography.models.core.nodes import CartographyNodeProperties
 from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.nodes import ExtraNodeLabels
 from cartography.models.core.relationships import CartographyRelProperties
 from cartography.models.core.relationships import CartographyRelSchema
 from cartography.models.core.relationships import LinkDirection
@@ -43,6 +44,9 @@ class OpenAIUserToOrganizationRel(CartographyRelSchema):
 @dataclass(frozen=True)
 class OpenAIUserSchema(CartographyNodeSchema):
     label: str = "OpenAIUser"
+    extra_node_labels: ExtraNodeLabels = ExtraNodeLabels(
+        ["UserAccount"]
+    )  # UserAccount label is used for ontology mapping
     properties: OpenAIUserNodeProperties = OpenAIUserNodeProperties()
     sub_resource_relationship: OpenAIUserToOrganizationRel = (
         OpenAIUserToOrganizationRel()

cartography/models/scaleway/iam/user.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from cartography.models.core.common import PropertyRef
 from cartography.models.core.nodes import CartographyNodeProperties
 from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.nodes import ExtraNodeLabels
 from cartography.models.core.relationships import CartographyRelProperties
 from cartography.models.core.relationships import CartographyRelSchema
 from cartography.models.core.relationships import LinkDirection
@@ -54,6 +55,9 @@ class ScalewayUserToOrganizationRel(CartographyRelSchema):
 @dataclass(frozen=True)
 class ScalewayUserSchema(CartographyNodeSchema):
     label: str = "ScalewayUser"
+    extra_node_labels: ExtraNodeLabels = ExtraNodeLabels(
+        ["UserAccount"]
+    )  # UserAccount label is used for ontology mapping
     properties: ScalewayUserNodeProperties = ScalewayUserNodeProperties()
     sub_resource_relationship: ScalewayUserToOrganizationRel = (
         ScalewayUserToOrganizationRel()

cartography/models/snipeit/asset.py

@@ -22,6 +22,7 @@ class SnipeitAssetNodeProperties(CartographyNodeProperties):
     lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
 
     # SnipeIT specific properties
+    name: PropertyRef = PropertyRef("name", extra_index=True)
     asset_tag: PropertyRef = PropertyRef("asset_tag")
     assigned_to: PropertyRef = PropertyRef("assigned_to.email")
     category: PropertyRef = PropertyRef("category.name")

cartography/models/snipeit/user.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from cartography.models.core.common import PropertyRef
 from cartography.models.core.nodes import CartographyNodeProperties
 from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.nodes import ExtraNodeLabels
 from cartography.models.core.relationships import CartographyRelProperties
 from cartography.models.core.relationships import CartographyRelSchema
 from cartography.models.core.relationships import LinkDirection
@@ -48,6 +49,9 @@ class SnipeitTenantToSnipeitUserRel(CartographyRelSchema):
 @dataclass(frozen=True)
 class SnipeitUserSchema(CartographyNodeSchema):
     label: str = "SnipeitUser"  # The label of the node
+    extra_node_labels: ExtraNodeLabels = ExtraNodeLabels(
+        ["UserAccount"]
+    )  # UserAccount label is used for ontology mapping
     properties: SnipeitUserNodeProperties = (
         SnipeitUserNodeProperties()
     )  # An object representing all properties

cartography/models/tailscale/device.py

@@ -17,7 +17,7 @@ class TailscaleDeviceNodeProperties(CartographyNodeProperties):
     id: PropertyRef = PropertyRef("nodeId")
     lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
     name: PropertyRef = PropertyRef("name")
-    hostname: PropertyRef = PropertyRef("hostname")
+    hostname: PropertyRef = PropertyRef("hostname", extra_index=True)
     client_version: PropertyRef = PropertyRef("clientVersion")
     update_available: PropertyRef = PropertyRef("updateAvailable")
     os: PropertyRef = PropertyRef("os")

cartography/models/tailscale/user.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from cartography.models.core.common import PropertyRef
 from cartography.models.core.nodes import CartographyNodeProperties
 from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.nodes import ExtraNodeLabels
 from cartography.models.core.relationships import CartographyRelProperties
 from cartography.models.core.relationships import CartographyRelSchema
 from cartography.models.core.relationships import LinkDirection
@@ -15,7 +16,8 @@ class TailscaleUserNodeProperties(CartographyNodeProperties):
     id: PropertyRef = PropertyRef("id")
     lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
     display_name: PropertyRef = PropertyRef("displayName")
-    login_name: PropertyRef = PropertyRef("loginName", extra_index=True)
+    login_name: PropertyRef = PropertyRef("loginName")
+    email: PropertyRef = PropertyRef("loginName", extra_index=True)
     profile_pic_url: PropertyRef = PropertyRef("profilePicUrl")
     created: PropertyRef = PropertyRef("created")
     type: PropertyRef = PropertyRef("type")
@@ -48,5 +50,8 @@ class TailscaleUserToTailnetRel(CartographyRelSchema):
 @dataclass(frozen=True)
 class TailscaleUserSchema(CartographyNodeSchema):
     label: str = "TailscaleUser"
+    extra_node_labels: ExtraNodeLabels = ExtraNodeLabels(
+        ["UserAccount"]
+    )  # UserAccount label is used for ontology mapping
     properties: TailscaleUserNodeProperties = TailscaleUserNodeProperties()
     sub_resource_relationship: TailscaleUserToTailnetRel = TailscaleUserToTailnetRel()