feat(sentinelone): ingest agent IP addresses (#2858)

### Type of change
- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update


### Summary

Adds SentinelOne agent IP address fields to `S1Agent`:

- `public_ip` from SentinelOne `externalIp`
- `local_ips` from non-loopback values in `networkInterfaces[].inet`

This helps correlate endpoint inventory with security findings that
reference either public source IPs or local endpoint IPs. Loopback
interface addresses are filtered out because they are not useful for
graph correlation.


### Related issues or links

- Fixes #


### Breaking changes

None. This only adds optional properties to existing `S1Agent` nodes.


### How was this tested?

- Validated against a live SentinelOne site-scoped API response in a
temporary local Neo4j database. The provider response included non-null
`externalIp` values and local interface `inet` values. The local
`S1Agent` sync loaded 5 agents, persisted `public_ip` for 5 agents, and
persisted non-loopback `local_ips` for 5 agents.

### Checklist

#### General
- [ ] I have read the [contributing
guidelines](https://cartography-cncf.github.io/cartography/dev/developer-guide.html).
- [x] The linter passes locally (`make test_lint`).
- [x] I have added/updated tests that prove my fix is effective or my
feature works.

#### Proof of functionality
- [ ] Screenshot showing the graph before and after changes.
- [x] New or updated unit/integration tests.

#### If you are adding or modifying a synced entity
- [x] Included Cartography sync logs from a real environment
demonstrating successful synchronization of the new/modified entity.
Logs should show:
  - The sync job starting and completing without errors
  - The number of nodes/relationships created or updated
  - Example:
    ```
INFO:cartography.intel.aws.ec2:Loading 42 EC2 instances for region
us-east-1
    INFO:cartography.intel.aws.ec2:Synced EC2 instances in 3.21 seconds
    ```

#### If you are changing a node or relationship
- [x] Updated the [schema
documentation](https://github.com/cartography-cncf/cartography/tree/master/docs/root/modules).
- [ ] Updated the [schema
README](https://github.com/cartography-cncf/cartography/blob/master/docs/schema/README.md).

#### If you are implementing a new intel module
- [ ] Used the NodeSchema [data
model](https://cartography-cncf.github.io/cartography/dev/writing-intel-modules.html#defining-a-node).


### Notes for reviewers

`public_ip` and `local_ips` are intentionally optional because
SentinelOne may omit those fields for some agents or scopes.

---------

Signed-off-by: Kunaal Sikka <kunaal@subimage.io>

Author: kunaals

cartography/intel/sentinelone/agent.py

@@ -1,4 +1,5 @@
 import logging
+from ipaddress import ip_address
 from typing import Any
 
 import neo4j
@@ -13,6 +14,25 @@
 logger = logging.getLogger(__name__)
 
 
+def _get_local_ips(agent: dict[str, Any]) -> list[str]:
+    local_ips: list[str] = []
+    for network_interface in agent.get("networkInterfaces") or []:
+        inet_values = network_interface.get("inet") or []
+        if isinstance(inet_values, str):
+            inet_values = [inet_values]
+        for ip in inet_values:
+            if not ip:
+                continue
+            try:
+                parsed_ip = ip_address(ip)
+            except ValueError:
+                continue
+            if parsed_ip.is_loopback:
+                continue
+            local_ips.append(ip)
+    return local_ips
+
+
 @timeit
 def get_agents(
     api_url: str,
@@ -61,6 +81,8 @@ def transform_agents(agent_list: list[dict[str, Any]]) -> list[dict[str, Any]]:
             # Optional fields - use .get() with None default
             "uuid": agent.get("uuid"),
             "computer_name": agent.get("computerName"),
+            "public_ip": agent.get("externalIp"),
+            "local_ips": _get_local_ips(agent),
             "firewall_enabled": agent.get("firewallEnabled"),
             "os_name": agent.get("osName"),
             "os_revision": agent.get("osRevision"),

cartography/models/sentinelone/agent.py

@@ -15,6 +15,8 @@ class S1AgentNodeProperties(CartographyNodeProperties):
     id: PropertyRef = PropertyRef("id", extra_index=True)
     uuid: PropertyRef = PropertyRef("uuid", extra_index=True)
     computer_name: PropertyRef = PropertyRef("computer_name", extra_index=True)
+    public_ip: PropertyRef = PropertyRef("public_ip", extra_index=True)
+    local_ips: PropertyRef = PropertyRef("local_ips")
     firewall_enabled: PropertyRef = PropertyRef("firewall_enabled")
     os_name: PropertyRef = PropertyRef("os_name")
     os_revision: PropertyRef = PropertyRef("os_revision")

docs/root/modules/sentinelone/schema.md

@@ -66,6 +66,8 @@ Represents a SentinelOne agent installed on an endpoint device.
 | **uuid** | The UUID of the agent |
 | **computer_name** | The name of the computer where the agent is installed |
 | **serial_number** | The serial number of the endpoint device |
+| public_ip | The public IP address reported by SentinelOne for the endpoint device |
+| local_ips | Local IPv4 addresses reported by SentinelOne network interfaces for the endpoint device |
 | firewall_enabled | Boolean indicating if the firewall is enabled |
 | os_name | The name of the operating system |
 | os_revision | The operating system revision/version |

tests/data/sentinelone/agent.py

@@ -7,6 +7,12 @@
         "id": AGENT_ID,
         "uuid": "uuid-123-456-789",
         "computerName": "test-computer-01",
+        "externalIp": "203.0.113.10",
+        "networkInterfaces": [
+            {
+                "inet": ["192.168.1.10", "127.0.0.1"],
+            },
+        ],
         "firewallEnabled": True,
         "osName": "Windows 10",
         "osRevision": "1909",
@@ -20,6 +26,15 @@
         "id": AGENT_ID_2,
         "uuid": "uuid-456-789-123",
         "computerName": "test-computer-02",
+        "externalIp": "203.0.113.11",
+        "networkInterfaces": [
+            {
+                "inet": ["10.0.0.20"],
+            },
+            {
+                "inet": ["127.0.0.1"],
+            },
+        ],
         "firewallEnabled": False,
         "osName": "Ubuntu 20.04",
         "osRevision": "5.4.0-89-generic",
@@ -33,6 +48,8 @@
         "id": AGENT_ID_3,
         "uuid": "uuid-789-123-456",
         "computerName": "test-computer-03",
+        "externalIp": None,
+        "networkInterfaces": [],
         "firewallEnabled": True,
         "osName": "macOS",
         "osRevision": "12.6.1",

tests/integration/cartography/intel/sentinelone/test_agent.py

@@ -49,6 +49,7 @@ def test_sync_agents(neo4j_session, mocker):
             AGENT_ID,
             "uuid-123-456-789",
             "test-computer-01",
+            "203.0.113.10",
             True,
             "Windows 10",
             "1909",
@@ -62,6 +63,7 @@ def test_sync_agents(neo4j_session, mocker):
             AGENT_ID_2,
             "uuid-456-789-123",
             "test-computer-02",
+            "203.0.113.11",
             False,
             "Ubuntu 20.04",
             "5.4.0-89-generic",
@@ -75,6 +77,7 @@ def test_sync_agents(neo4j_session, mocker):
             AGENT_ID_3,
             "uuid-789-123-456",
             "test-computer-03",
+            None,
             True,
             "macOS",
             "12.6.1",
@@ -93,6 +96,7 @@ def test_sync_agents(neo4j_session, mocker):
             "id",
             "uuid",
             "computer_name",
+            "public_ip",
             "firewall_enabled",
             "os_name",
             "os_revision",
@@ -106,6 +110,18 @@ def test_sync_agents(neo4j_session, mocker):
 
     assert actual_nodes == expected_nodes
 
+    local_ips = {
+        (record["id"], tuple(record["local_ips"]))
+        for record in neo4j_session.run(
+            "MATCH (a:S1Agent) RETURN a.id AS id, a.local_ips AS local_ips",
+        )
+    }
+    assert local_ips == {
+        (AGENT_ID, ("192.168.1.10",)),
+        (AGENT_ID_2, ("10.0.0.20",)),
+        (AGENT_ID_3, ()),
+    }
+
     # Verify that relationships to the account were created
     expected_rels = {
         (AGENT_ID, TEST_ACCOUNT_ID),

tests/unit/cartography/intel/sentinelone/test_agent.py

@@ -63,6 +63,8 @@ def test_transform_agents():
     assert agent1["id"] == AGENT_ID
     assert agent1["uuid"] == "uuid-123-456-789"
     assert agent1["computer_name"] == "test-computer-01"
+    assert agent1["public_ip"] == "203.0.113.10"
+    assert agent1["local_ips"] == ["192.168.1.10"]
     assert agent1["firewall_enabled"] is True
     assert agent1["os_name"] == "Windows 10"
     assert agent1["os_revision"] == "1909"
@@ -75,12 +77,16 @@ def test_transform_agents():
     # Test second agent (Linux with different values)
     agent2 = result[1]
     assert agent2["id"] == AGENT_ID_2
+    assert agent2["public_ip"] == "203.0.113.11"
+    assert agent2["local_ips"] == ["10.0.0.20"]
     assert agent2["firewall_enabled"] is False  # Boolean type preservation
     assert agent2["os_name"] == "Ubuntu 20.04"
 
     # Test third agent (macOS with None fields)
     agent3 = result[2]
     assert agent3["id"] == AGENT_ID_3
+    assert agent3["public_ip"] is None
+    assert agent3["local_ips"] == []
     assert agent3["domain"] is None  # None value handling
     assert agent3["last_successful_scan"] is None  # None value handling
 
@@ -100,6 +106,8 @@ def test_transform_agents_missing_optional_fields():
     # Optional fields should be None
     assert agent["uuid"] is None
     assert agent["computer_name"] is None
+    assert agent["public_ip"] is None
+    assert agent["local_ips"] == []
     assert agent["firewall_enabled"] is None
     assert agent["os_name"] is None
     assert agent["os_revision"] is None
@@ -126,6 +134,25 @@ def test_transform_agents_missing_required_field():
         transform_agents(test_data)
 
 
+def test_transform_agents_handles_unexpected_local_ip_shapes():
+    """
+    Test that transform_agents handles scalar local IPs and invalid local IPs.
+    """
+    result = transform_agents(
+        [
+            {
+                "id": "unexpected-local-ip-agent",
+                "networkInterfaces": [
+                    {"inet": "192.168.1.11"},
+                    {"inet": ["not-an-ip-address", "127.0.0.1", "10.0.0.11"]},
+                ],
+            },
+        ],
+    )
+
+    assert result[0]["local_ips"] == ["192.168.1.11", "10.0.0.11"]
+
+
 def test_transform_agents_empty_list():
     """
     Test that transform_agents handles empty input list