Knowledge Graph

SoCMate builds a persistent knowledge graph from every investigation. As you investigate security incidents, the graph grows with new entities and relationships, creating an institutional memory of your security landscape.

Overview

The knowledge graph captures two things:

Entities — Security-relevant objects like IP addresses, user accounts, hostnames, domains, file hashes, and email addresses
Relationships — Connections between entities discovered during investigations, such as “user signed in from IP” or “host connected to domain”

Each entity is linked to the investigations where it was discovered, enabling you to trace the history of any entity across your entire investigation history.

Entity Types

Type	Description	Examples
`ip`	IPv4 or IPv6 addresses	`203.0.113.50`, `2001:db8::1`
`user`	User accounts (UPN or email)	`john@example.com`, `admin@corp.local`
`host`	Hostnames or device names	`SRV-DC01`, `LAPTOP-A1B2C3`
`domain`	Domain names	`evil-phishing.com`, `cdn.legitimate.com`
`hash`	File hashes (MD5, SHA1, SHA256)	`a1b2c3d4e5f6...`
`email`	Email addresses (distinct from user accounts)	`sender@phishing.com`
`url`	Full URLs	`https://evil-phishing.com/payload.exe`
`process`	Process names	`powershell.exe`, `cmd.exe`

Relationship Types

Relationship	Description	Example
`SIGNED_IN_FROM`	User authenticated from an IP	`john@example.com` -> `203.0.113.50`
`CONNECTED_TO`	IP or host established a connection	`203.0.113.50` -> `SRV-DC01`
`RESOLVED_TO`	Domain resolved to an IP	`evil-phishing.com` -> `203.0.113.50`
`RAN_ON`	Process executed on a host	`powershell.exe` -> `SRV-DC01`
`DOWNLOADED_FROM`	File downloaded from a URL	`payload.exe` -> `https://evil.com/payload`
`COMMUNICATED_WITH`	Host communicated with a domain or IP	`LAPTOP-A1B2C3` -> `evil-phishing.com`
`ASSOCIATED_WITH`	General association between entities	`hash_abc123` -> `malware_campaign_xyz`
`INVESTIGATED_IN`	Entity was part of an investigation	`203.0.113.50` -> `sess_abc123`

Exploring the Graph

Visual Explorer

Navigate to Knowledge Graph in the sidebar to open the visual graph explorer. You can:

Search for an entity — Type an IP, username, hostname, or domain to center the graph on that entity
Expand neighborhoods — Click an entity to load its connected nodes
Filter by type — Show only specific entity types (IPs, users, hosts)
Filter by time — Show entities from a specific investigation time range
Adjust depth — Control how many relationship hops to display (1-3)

API: Entity Neighborhood

Get the neighborhood of a specific entity:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/graph/entity/203.0.113.50?depth=2" \
  -H "Authorization: Bearer <token>"

Response:

{
  "nodes": [
    {
      "id": "203.0.113.50",
      "type": "ip",
      "properties": {
        "first_seen": "2026-03-10T08:00:00Z",
        "last_seen": "2026-03-15T14:30:00Z"
      }
    },
    {
      "id": "john@example.com",
      "type": "user",
      "properties": { "first_seen": "2026-03-11T14:22:00Z" }
    },
    {
      "id": "SRV-DC01",
      "type": "host",
      "properties": { "first_seen": "2026-03-12T02:30:00Z" }
    }
  ],
  "edges": [
    {
      "source": "john@example.com",
      "target": "203.0.113.50",
      "type": "SIGNED_IN_FROM"
    },
    {
      "source": "203.0.113.50",
      "target": "SRV-DC01",
      "type": "CONNECTED_TO"
    }
  ]
}

The depth parameter controls traversal depth (1 to 3 hops).

API: Investigation Subgraph

Get the knowledge subgraph for a specific investigation session:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/graph/investigation/sess_abc123" \
  -H "Authorization: Bearer <token>"

Returns all entities and relationships discovered during that investigation.

API: Entity Search

Search for entities across the knowledge graph:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/graph/search?q=203.0.113" \
  -H "Authorization: Bearer <token>"

Response:

{
  "results": [
    { "value": "203.0.113.50", "type": "ip", "score": 0.95 },
    { "value": "203.0.113.51", "type": "ip", "score": 0.90 }
  ]
}

You can also search entities via the search endpoint:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/search/entities?q=203.0.113" \
  -H "Authorization: Bearer <token>"

This returns entity metadata including the number of investigations where the entity appears and first/last seen timestamps.

Entity Diagrams

Each investigation produces an entity relationship diagram that visualizes the discovered entities and their connections. These diagrams are available in the UI and via the API.

Generate a Diagram

curl -X POST https://api.socmate.yourcompany.com/api/v1/entity-diagrams/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "entities": [
      { "value": "203.0.113.50", "type": "ip" },
      { "value": "john@example.com", "type": "user" },
      { "value": "SRV-DC01", "type": "host" }
    ],
    "relationships": [
      { "source": "john@example.com", "target": "203.0.113.50", "type": "SIGNED_IN_FROM" },
      { "source": "203.0.113.50", "target": "SRV-DC01", "type": "CONNECTED_TO" }
    ]
  }'

Retrieve a Diagram

curl -X GET https://api.socmate.yourcompany.com/api/v1/entity-diagrams/diag_001 \
  -H "Authorization: Bearer <token>"

How Entities Are Discovered

Entities are extracted at two points during an investigation:

Query Analysis — SoCMate parses the user’s query and identifies entities mentioned directly (e.g., “Check IP 203.0.113.50”)
Results Processing — After the investigation completes, all entities found in query results and the investigation report are extracted and persisted to the knowledge graph

This means the knowledge graph contains both entities the user mentioned and entities discovered through the investigation process.

Cross-Investigation Intelligence

The knowledge graph enables powerful cross-investigation queries:

“Have we seen this IP before?” — Check if an IP appeared in previous investigations
“What other hosts has this user accessed?” — Trace user activity across investigations
“Is this domain connected to known malicious infrastructure?” — Follow relationship chains
“Which investigations involved this entity?” — Get the full investigation history for any entity

This institutional memory grows more valuable over time as your team conducts more investigations.

​Overview

​Entity Types

​Relationship Types

​Exploring the Graph

​Visual Explorer

​API: Entity Neighborhood

​API: Investigation Subgraph

​API: Entity Search

​Entity Diagrams

​Generate a Diagram

​Retrieve a Diagram

​How Entities Are Discovered

​Cross-Investigation Intelligence