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

cartography/intel/tailscale/devices.py

@@ -0,0 +1,127 @@
+import logging
+from typing import Any
+from typing import Dict
+from typing import List
+
+import neo4j
+import requests
+
+from cartography.client.core.tx import load
+from cartography.graph.job import GraphJob
+from cartography.models.tailscale.device import TailscaleDeviceSchema
+from cartography.models.tailscale.tag import TailscaleTagSchema
+from cartography.util import timeit
+
+logger = logging.getLogger(__name__)
+# Connect and read timeouts of 60 seconds each; see https://requests.readthedocs.io/en/master/user/advanced/#timeouts
+_TIMEOUT = (60, 60)
+
+
+@timeit
+def sync(
+    neo4j_session: neo4j.Session,
+    api_session: requests.Session,
+    common_job_parameters: Dict[str, Any],
+    org: str,
+) -> List[Dict]:
+    devices = get(
+        api_session,
+        common_job_parameters["BASE_URL"],
+        org,
+    )
+    tags = transform(devices)
+    load_devices(
+        neo4j_session,
+        devices,
+        org,
+        common_job_parameters["UPDATE_TAG"],
+    )
+    load_tags(
+        neo4j_session,
+        tags,
+        org,
+        common_job_parameters["UPDATE_TAG"],
+    )
+    cleanup(neo4j_session, common_job_parameters)
+    return devices
+
+
+@timeit
+def get(
+    api_session: requests.Session,
+    base_url: str,
+    org: str,
+) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    req = api_session.get(
+        f"{base_url}/tailnet/{org}/devices",
+        timeout=_TIMEOUT,
+    )
+    req.raise_for_status()
+    results = req.json()["devices"]
+    return results
+
+
+def transform(
+    raw_data: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Extracts tags from the raw data and returns a list of dictionaries"""
+    transformed_tags: Dict[str, Dict[str, Any]] = {}
+    # Transform the raw data into the format expected by the load function
+    for device in raw_data:
+        for raw_tag in device.get("tags", []):
+            if raw_tag not in transformed_tags:
+                transformed_tags[raw_tag] = {
+                    "id": raw_tag,
+                    "name": raw_tag.split(":")[-1],
+                    "devices": [device["nodeId"]],
+                }
+            else:
+                transformed_tags[raw_tag]["devices"].append(device["nodeId"])
+    return list(transformed_tags.values())
+
+
+@timeit
+def load_devices(
+    neo4j_session: neo4j.Session,
+    data: List[Dict[str, Any]],
+    org: str,
+    update_tag: int,
+) -> None:
+    logger.info(f"Loading {len(data)} Tailscale Devices to the graph")
+    load(
+        neo4j_session,
+        TailscaleDeviceSchema(),
+        data,
+        lastupdated=update_tag,
+        org=org,
+    )
+
+
+@timeit
+def load_tags(
+    neo4j_session: neo4j.Session,
+    data: List[Dict[str, Any]],
+    org: str,
+    update_tag: int,
+) -> None:
+    logger.info(f"Loading {len(data)} Tailscale Tags to the graph")
+    load(
+        neo4j_session,
+        TailscaleTagSchema(),
+        data,
+        lastupdated=update_tag,
+        org=org,
+    )
+
+
+@timeit
+def cleanup(
+    neo4j_session: neo4j.Session, common_job_parameters: Dict[str, Any]
+) -> None:
+    GraphJob.from_node_schema(TailscaleDeviceSchema(), common_job_parameters).run(
+        neo4j_session
+    )
+    GraphJob.from_node_schema(TailscaleTagSchema(), common_job_parameters).run(
+        neo4j_session
+    )

cartography/intel/tailscale/postureintegrations.py

@@ -0,0 +1,81 @@
+import logging
+from typing import Any
+from typing import Dict
+from typing import List
+
+import neo4j
+import requests
+
+from cartography.client.core.tx import load
+from cartography.graph.job import GraphJob
+from cartography.models.tailscale.postureintegration import (
+    TailscalePostureIntegrationSchema,
+)
+from cartography.util import timeit
+
+logger = logging.getLogger(__name__)
+# Connect and read timeouts of 60 seconds each; see https://requests.readthedocs.io/en/master/user/advanced/#timeouts
+_TIMEOUT = (60, 60)
+
+
+@timeit
+def sync(
+    neo4j_session: neo4j.Session,
+    api_session: requests.Session,
+    common_job_parameters: Dict[str, Any],
+    org: str,
+) -> None:
+    postureintegrations = get(
+        api_session,
+        common_job_parameters["BASE_URL"],
+        org,
+    )
+    load_postureintegrations(
+        neo4j_session,
+        postureintegrations,
+        org,
+        common_job_parameters["UPDATE_TAG"],
+    )
+    cleanup(neo4j_session, common_job_parameters)
+
+
+@timeit
+def get(
+    api_session: requests.Session,
+    base_url: str,
+    org: str,
+) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    req = api_session.get(
+        f"{base_url}/tailnet/{org}/posture/integrations",
+        timeout=_TIMEOUT,
+    )
+    req.raise_for_status()
+    results = req.json()["integrations"]
+    return results
+
+
+@timeit
+def load_postureintegrations(
+    neo4j_session: neo4j.Session,
+    data: List[Dict[str, Any]],
+    org: str,
+    update_tag: int,
+) -> None:
+    logger.info(f"Loading {len(data)} Tailscale PostureIntegrations to the graph")
+    load(
+        neo4j_session,
+        TailscalePostureIntegrationSchema(),
+        data,
+        lastupdated=update_tag,
+        org=org,
+    )
+
+
+@timeit
+def cleanup(
+    neo4j_session: neo4j.Session, common_job_parameters: Dict[str, Any]
+) -> None:
+    GraphJob.from_node_schema(
+        TailscalePostureIntegrationSchema(), common_job_parameters
+    ).run(neo4j_session)

cartography/intel/tailscale/tailnets.py

@@ -0,0 +1,76 @@
+import logging
+from typing import Any
+from typing import Dict
+from typing import List
+
+import neo4j
+import requests
+
+from cartography.client.core.tx import load
+from cartography.graph.job import GraphJob
+from cartography.models.tailscale.tailnet import TailscaleTailnetSchema
+from cartography.util import timeit
+
+logger = logging.getLogger(__name__)
+# Connect and read timeouts of 60 seconds each; see https://requests.readthedocs.io/en/master/user/advanced/#timeouts
+_TIMEOUT = (60, 60)
+
+
+@timeit
+def sync(
+    neo4j_session: neo4j.Session,
+    api_session: requests.Session,
+    common_job_parameters: Dict[str, Any],
+    org: str,
+) -> None:
+    tailnet = get(
+        api_session,
+        common_job_parameters["BASE_URL"],
+        org,
+    )
+    load_tailnets(
+        neo4j_session,
+        [tailnet],
+        org,
+        common_job_parameters["UPDATE_TAG"],
+    )
+    cleanup(neo4j_session, common_job_parameters)
+
+
+@timeit
+def get(
+    api_session: requests.Session,
+    base_url: str,
+    org: str,
+) -> Dict[str, Any]:
+    req = api_session.get(
+        f"{base_url}/tailnet/{org}/settings",
+        timeout=_TIMEOUT,
+    )
+    req.raise_for_status()
+    return req.json()
+
+
+@timeit
+def load_tailnets(
+    neo4j_session: neo4j.Session,
+    data: List[Dict[str, Any]],
+    org: str,
+    update_tag: int,
+) -> None:
+    load(
+        neo4j_session,
+        TailscaleTailnetSchema(),
+        data,
+        lastupdated=update_tag,
+        org=org,
+    )
+
+
+@timeit
+def cleanup(
+    neo4j_session: neo4j.Session, common_job_parameters: Dict[str, Any]
+) -> None:
+    GraphJob.from_node_schema(TailscaleTailnetSchema(), common_job_parameters).run(
+        neo4j_session
+    )

cartography/intel/tailscale/users.py

@@ -0,0 +1,80 @@
+import logging
+from typing import Any
+from typing import Dict
+from typing import List
+
+import neo4j
+import requests
+
+from cartography.client.core.tx import load
+from cartography.graph.job import GraphJob
+from cartography.models.tailscale.user import TailscaleUserSchema
+from cartography.util import timeit
+
+logger = logging.getLogger(__name__)
+# Connect and read timeouts of 60 seconds each; see https://requests.readthedocs.io/en/master/user/advanced/#timeouts
+_TIMEOUT = (60, 60)
+
+
+@timeit
+def sync(
+    neo4j_session: neo4j.Session,
+    api_session: requests.Session,
+    common_job_parameters: Dict[str, Any],
+    org: str,
+) -> List[Dict]:
+    users = get(
+        api_session,
+        common_job_parameters["BASE_URL"],
+        org,
+    )
+    load_users(
+        neo4j_session,
+        users,
+        org,
+        common_job_parameters["UPDATE_TAG"],
+    )
+    cleanup(neo4j_session, common_job_parameters)
+    return users
+
+
+@timeit
+def get(
+    api_session: requests.Session,
+    base_url: str,
+    org: str,
+) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    req = api_session.get(
+        f"{base_url}/tailnet/{org}/users",
+        timeout=_TIMEOUT,
+    )
+    req.raise_for_status()
+    results = req.json()["users"]
+    return results
+
+
+@timeit
+def load_users(
+    neo4j_session: neo4j.Session,
+    data: List[Dict[str, Any]],
+    org: str,
+    update_tag: int,
+) -> None:
+    logger.info(f"Loading {len(data)} Tailscale Users to the graph")
+    load(
+        neo4j_session,
+        TailscaleUserSchema(),
+        data,
+        lastupdated=update_tag,
+        org=org,
+    )
+
+
+@timeit
+def cleanup(
+    neo4j_session: neo4j.Session, common_job_parameters: Dict[str, Any]
+) -> None:
+    GraphJob.from_node_schema(TailscaleUserSchema(), common_job_parameters).run(
+        neo4j_session
+    )

cartography/intel/tailscale/utils.py

@@ -0,0 +1,132 @@
+import json
+import re
+from typing import Any
+from typing import Dict
+from typing import List
+
+
+class ACLParser:
+    """ACLParser is a class that parses Tailscale ACLs to extract data.
+
+    It removes comments and trailing commas from the ACL string
+    and converts it to a JSON object. It then provides methods
+    to extract groups and tags from the ACL.
+    The ACL string is expected to be in a format similar to JSON,
+    but with some Tailscale-specific syntax. The parser handles
+    single-line comments (//) and multi-line comments (/* */)
+    and removes trailing commas from the JSON-like structure.
+    The parser also handles Tailscale-specific syntax for groups
+    and tags, which may include user and group identifiers.
+    The parser is initialized with a raw ACL string, which is
+    processed to remove comments and trailing commas.
+
+    Args:
+        raw_acl (str): The raw ACL string to be parsed.
+
+    Attributes:
+        data (dict): The parsed JSON object representing the ACL.
+    """
+
+    RE_SINGLE_LINE_COMMENT = re.compile(r'("(?:(?=(\\?))\2.)*?")|(?:\/{2,}.*)')
+    RE_MULTI_LINE_COMMENT = re.compile(
+        r'("(?:(?=(\\?))\2.)*?")|(?:\/\*(?:(?!\*\/).)+\*\/)', flags=re.M | re.DOTALL
+    )
+    RE_TRAILING_COMMA = re.compile(r",(?=\s*?[\}\]])")
+
+    def __init__(self, raw_acl: str) -> None:
+        # Tailscale ACL use comments and trailing commas
+        # that are not valid JSON
+        filtered_json_string = self.RE_SINGLE_LINE_COMMENT.sub(r"\1", raw_acl)
+        filtered_json_string = self.RE_MULTI_LINE_COMMENT.sub(
+            r"\1", filtered_json_string
+        )
+        filtered_json_string = self.RE_TRAILING_COMMA.sub("", filtered_json_string)
+        self.data = json.loads(filtered_json_string)
+
+    def get_groups(self) -> List[Dict[str, Any]]:
+        """
+        Get all groups from the ACL
+
+        :return: list of groups
+        """
+        result: List[Dict[str, Any]] = []
+        groups = self.data.get("groups", {})
+        for group_id, members in groups.items():
+            group_name = group_id.split(":")[-1]
+            users_members = []
+            sub_groups = []
+            domain_members = []
+            for member in members:
+                if member.startswith("group:") or member.startswith("autogroup:"):
+                    sub_groups.append(member)
+                elif member.startswith("user:*@"):
+                    domain_members.append(member[7:])
+                elif member.startswith("user:"):
+                    users_members.append(member[5:])
+                else:
+                    users_members.append(member)
+            result.append(
+                {
+                    "id": group_id,
+                    "name": group_name,
+                    "members": users_members,
+                    "sub_groups": sub_groups,
+                    "domain_members": domain_members,
+                }
+            )
+        return result
+
+    def get_tags(self) -> List[Dict[str, Any]]:
+        """
+        Get all tags from the ACL
+
+        :return: list of tags
+        """
+        result: List[Dict[str, Any]] = []
+        for tag, owners in self.data.get("tagOwners", {}).items():
+            tag_name = tag.split(":")[-1]
+            user_owners = []
+            group_owners = []
+            domain_owners = []
+            for owner in owners:
+                if owner.startswith("group:") or owner.startswith("autogroup:"):
+                    group_owners.append(owner)
+                elif owner.startswith("user:*@"):
+                    domain_owners.append(owner[7:])
+                elif owner.startswith("user:"):
+                    user_owners.append(owner[5:])
+                else:
+                    user_owners.append(owner)
+            result.append(
+                {
+                    "id": tag,
+                    "name": tag_name,
+                    "owners": user_owners,
+                    "group_owners": group_owners,
+                    "domain_owners": domain_owners,
+                }
+            )
+        return result
+
+
+def role_to_group(role: str) -> list[str]:
+    """Convert Tailscale role to group
+
+    This function is used to convert Tailscale role to autogroup
+    group. The autogroup is used to manage the access control
+    in Tailscale.
+
+    Args:
+        role (str): The role of the user in Tailscale. (eg: owner, admin, member, etc)
+
+    Returns:
+        list[str]: The list of autogroup that the user belongs to. (eg: autogroup:admin, autogroup:member, etc)
+    """
+    result: list[str] = []
+    result.append(f"autogroup:{role}")
+    if role == "owner":
+        result.append("autogroup:admin")
+        result.append("autogroup:member")
+    elif role in ("admin", "auditor", "billing-admin", "it-admin", "network-admin"):
+        result.append("autogroup:member")
+    return result