cartography 0.104.0rc2__py3-none-any.whl → 0.123.0__py3-none-any.whl

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

@@ -0,0 +1,140 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+# ThirdPartyApp ontology fields:
+# client_id (REQUIRED) - OAuth client identifier
+# name (REQUIRED) - Display name of the third-party application
+# enabled - Whether the third-party app is enabled/active
+# native_app - Whether this is a native application (vs web)
+# protocol - OAuth protocol type (oauth2, openid-connect, saml, etc.)
+
+googleworkspace_mapping = OntologyMapping(
+    module_name="googleworkspace",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="GoogleWorkspaceOAuthApp",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="client_id",
+                    node_field="client_id",
+                    required=True,
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name",
+                    node_field="display_text",
+                    required=True,
+                ),
+                # enabled: Not available - Google Workspace third-party apps don't have an enabled/disabled state
+                OntologyFieldMapping(
+                    ontology_field="native_app",
+                    node_field="native_app",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="protocol",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "oauth2"},
+                ),
+            ],
+        ),
+    ],
+)
+
+keycloak_mapping = OntologyMapping(
+    module_name="keycloak",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="KeycloakClient",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="client_id",
+                    node_field="client_id",
+                    required=True,
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name",
+                    node_field="name",
+                    required=True,
+                ),
+                OntologyFieldMapping(
+                    ontology_field="enabled",
+                    node_field="enabled",
+                ),
+                # native_app: Not available - Keycloak doesn't distinguish native vs web apps in this field
+                OntologyFieldMapping(
+                    ontology_field="protocol",
+                    node_field="protocol",
+                ),
+            ],
+        ),
+    ],
+)
+
+entra_mapping = OntologyMapping(
+    module_name="entra",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="EntraApplication",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="client_id",
+                    node_field="app_id",
+                    required=True,
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name",
+                    node_field="display_name",
+                    required=True,
+                ),
+                # enabled: Not available - Entra applications don't have an enabled field in current schema
+                # native_app: Not available - Application type not currently ingested
+                OntologyFieldMapping(
+                    ontology_field="protocol",
+                    node_field="",
+                    special_handling="static_value",
+                    extra={"value": "oauth2"},
+                ),
+            ],
+        ),
+    ],
+)
+
+okta_mapping = OntologyMapping(
+    module_name="okta",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="OktaApplication",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="client_id",
+                    node_field="id",  # Note: This is Okta's internal app ID, not OAuth client_id
+                    required=True,
+                ),
+                OntologyFieldMapping(
+                    ontology_field="name",
+                    node_field="label",
+                    required=True,
+                ),
+                OntologyFieldMapping(
+                    ontology_field="enabled",
+                    node_field="status",
+                    extra={"values": ["ACTIVE"]},
+                    special_handling="equal_boolean",
+                ),
+                # native_app: Not available - Application type not distinguished in current schema
+                OntologyFieldMapping(
+                    ontology_field="protocol",
+                    node_field="sign_on_mode",
+                ),
+            ],
+        ),
+    ],
+)
+
+THIRDPARTYAPPS_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "googleworkspace": googleworkspace_mapping,
+    "keycloak": keycloak_mapping,
+    "entra": entra_mapping,
+    "okta": okta_mapping,
+}

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

@@ -0,0 +1,416 @@
+from cartography.models.ontology.mapping.specs import OntologyFieldMapping
+from cartography.models.ontology.mapping.specs import OntologyMapping
+from cartography.models.ontology.mapping.specs import OntologyNodeMapping
+
+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"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="active", node_field="account_enabled"
+                ),
+            ],
+        ),
+    ],
+)
+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"),
+                OntologyFieldMapping(
+                    ontology_field="has_mfa",
+                    node_field="multifactor",
+                    special_handling="to_boolean",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="disabled",
+                    special_handling="invert_boolean",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="last_login"
+                ),
+            ],
+        ),
+    ],
+)
+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"),
+                OntologyFieldMapping(
+                    ontology_field="has_mfa", node_field="is_enrolled_in_2_sv"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="suspended",
+                    extra={"fields": ["archived"]},
+                    special_handling="nor_boolean",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="last_login_time"
+                ),
+            ],
+        ),
+    ],
+)
+googleworkspace_mapping = OntologyMapping(
+    module_name="googleworkspace",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="GoogleWorkspaceUser",
+            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"),
+                OntologyFieldMapping(
+                    ontology_field="has_mfa", node_field="is_enrolled_in_2_sv"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="suspended",
+                    extra={"fields": ["archived"]},
+                    special_handling="nor_boolean",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="last_login_time"
+                ),
+            ],
+        ),
+    ],
+)
+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"),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="status",
+                    extra={"values": ["accepted"]},
+                    special_handling="equal_boolean",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="has_mfa",
+                    node_field="two_factor_authentication_enabled",
+                ),
+            ],
+        ),
+    ],
+)
+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"),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="last_login"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="status",
+                    extra={"values": ["active", "bypass"]},
+                    special_handling="equal_boolean",
+                ),
+            ],
+        ),
+    ],
+)
+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"),
+                OntologyFieldMapping(
+                    ontology_field="has_mfa", node_field="has_2fa_enabled"
+                ),
+            ],
+        ),
+    ],
+)
+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"),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="enabled",
+                ),
+                OntologyFieldMapping(ontology_field="has_mfa", node_field="totp"),
+            ],
+        ),
+    ],
+)
+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="firstname", node_field="first_name"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="last_name"),
+                OntologyFieldMapping(ontology_field="username", node_field="username"),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="locked",
+                    special_handling="invert_boolean",
+                ),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="last_login_at"
+                ),
+                OntologyFieldMapping(ontology_field="has_mfa", node_field="mfa"),
+            ],
+        ),
+    ],
+)
+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"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="username", node_field="login_name"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="active",
+                    node_field="status",
+                    extra={"values": ["active", "idle"]},
+                    special_handling="equal_boolean",
+                ),
+            ],
+        ),
+    ],
+)
+okta_mapping = OntologyMapping(
+    module_name="okta",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="OktaUser",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="first_name"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="last_name"),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="last_login"
+                ),
+            ],
+        ),
+    ],
+)
+aws_mapping = OntologyMapping(
+    module_name="aws",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="AWSUser",
+            eligible_for_source=False,
+            fields=[
+                OntologyFieldMapping(ontology_field="username", node_field="name"),
+                OntologyFieldMapping(
+                    ontology_field="lastactivity", node_field="passwordlastused"
+                ),
+            ],
+        ),
+        OntologyNodeMapping(
+            node_label="AWSSSOUser",
+            eligible_for_source=False,
+            fields=[
+                OntologyFieldMapping(ontology_field="username", node_field="user_name")
+            ],
+        ),
+    ],
+)
+slack_mapping = OntologyMapping(
+    module_name="slack",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="SlackUser",
+            fields=[
+                OntologyFieldMapping(ontology_field="email", node_field="email"),
+                OntologyFieldMapping(ontology_field="username", node_field="name"),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="first_name"
+                ),
+                OntologyFieldMapping(ontology_field="lastname", node_field="last_name"),
+                OntologyFieldMapping(ontology_field="fullname", node_field="real_name"),
+                OntologyFieldMapping(ontology_field="has_mfa", node_field="has_mfa"),
+                OntologyFieldMapping(ontology_field="inactive", node_field="deleted"),
+                OntologyFieldMapping(
+                    ontology_field="system_account",
+                    node_field="is_bot",
+                    extra={"fields": ["is_app_user"]},
+                    special_handling="or_boolean",
+                ),
+            ],
+        ),
+    ],
+)
+
+# UserAccount fields:
+# has_mfa
+# inactive
+# lastactivity
+
+USERACCOUNTS_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "entra": entra_mapping,
+    "lastpass": lastpass_mapping,
+    "gsuite": gsuite_mapping,
+    "anthropic": anthropic_mapping,
+    "airbyte": airbyte_mapping,
+    "cloudflare": cloudflare_mapping,
+    "duo": duo_mapping,
+    "github": github_mapping,
+    "keycloak": keycloak_mapping,
+    "openai": openai_mapping,
+    "scaleway": scaleway_mapping,
+    "snipeit": snipeit_mapping,
+    "tailscale": tailscale_mapping,
+    "okta": okta_mapping,
+    "aws": aws_mapping,
+    "googleworkspace": googleworkspace_mapping,
+    "slack": slack_mapping,
+}

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

@@ -0,0 +1,63 @@
+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
+
+useraccount_mapping = OntologyMapping(
+    module_name="ontology",
+    nodes=[
+        OntologyNodeMapping(
+            node_label="UserAccount",
+            fields=[
+                OntologyFieldMapping(
+                    ontology_field="email", node_field="_ont_email", required=True
+                ),
+                OntologyFieldMapping(
+                    ontology_field="fullname", node_field="_ont_fullname"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="firstname", node_field="_ont_firstname"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="lastname", node_field="_ont_lastname"
+                ),
+                OntologyFieldMapping(
+                    ontology_field="inactive", node_field="_ont_inactive"
+                ),
+            ],
+        ),
+    ],
+    rels=[
+        OntologyRelMapping(
+            __comment__="Link AWSSSOUser to User based on external_id mapping to arbitrary UserAccount node",
+            query="MATCH (sso:AWSSSOUser) MATCH (u:User)-[:HAS_ACCOUNT]->(:UserAccount {id: sso.external_id}) MERGE (u)-[r:HAS_ACCOUNT]->(sso) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        ),
+        OntologyRelMapping(
+            __comment__="Link GitHubUser to User based on organization_verified_domain_emails on GitHubUser node",
+            query="MATCH (u:User) WHERE u.email is not NULL MATCH (g:GitHubUser) WHERE u.email in g.organization_verified_domain_emails MERGE (u)-[r:HAS_ACCOUNT]->(g) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        ),
+        OntologyRelMapping(
+            __comment__="Link User to APIKey",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:UserAccount)-[:OWNS|HAS]->(k:APIKey) MERGE (u)-[r:OWNS]->(k) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        ),
+        OntologyRelMapping(
+            __comment__="Link User to ThirdPartyApp",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:UserAccount)-[authr:AUTHORIZED|APPLICATION]->(a:ThirdPartyApp) MERGE (u)-[r:AUTHORIZED]->(a) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG, r.scopes = coalesce(authr.scopes, [])",
+            iterative=False,
+        ),
+        # TODO: Change this when we have a Ontology Group node
+        OntologyRelMapping(
+            __comment__="Link User to ThirdPartyApp (via groups) (okta specific)",
+            query="MATCH (u:User)-[:HAS_ACCOUNT]->(:OktaUser)-[:MEMBER_OF_OKTA_GROUP]->(:OktaGroup)-[:APPLICATION]->(a:ThirdPartyApp) MERGE (u)-[r:AUTHORIZED]->(a) ON CREATE SET r.firstseen = timestamp() SET r.lastupdated = $UPDATE_TAG",
+            iterative=False,
+        ),
+    ],
+)
+
+
+USERS_ONTOLOGY_MAPPING: dict[str, OntologyMapping] = {
+    "ontology": useraccount_mapping,
+}