Relationship Taxonomy¶

This document explains the relationship taxonomy system that defines which connections are valid between asset types in the open-asset-model. The taxonomy is implemented as a nested map structure that maps source asset types to allowed relationship labels, relation types, and destination asset types. This page covers the central dispatcher function assetTypeRelations, the three public query functions (GetAssetOutgoingRelations, GetTransformAssetTypes, ValidRelationship), and the complete set of relationship definitions for all 21 asset types.

For information about the actual implementations of relation types (BasicDNSRelation, SimpleRelation, etc.), see 4.2 and 4.3. For the core Relation interface definition, see 2.2.

The Three-Level Nested Map Structure¶

The relationship taxonomy uses a three-level nested map to define valid relationships with fine-grained control:

map[string]map[RelationType][]AssetType
     │           │              │
     │           │              └─ Valid destination asset types
     │           └─ Relation type (BasicDNS, Simple, Port, etc.)
     └─ Relationship label (semantic meaning)

This structure allows the same label to map to different destination types depending on the RelationType used. For example, FQDN's "dns_record" label can point to different destinations based on whether it's a BasicDNSRelation (A/AAAA/CNAME records) or PrefDNSRelation (MX records).

Structure Diagram¶

graph TD
    Root["map[string]map[RelationType][]AssetType"]

    Level1["Outer Map Key: Label (string)"]
    Level2["Middle Map Key: RelationType"]
    Level3["Inner Slice: []AssetType"]

    Root --> Level1
    Level1 --> Level2
    Level2 --> Level3

    Example1["Example: fqdnRels['dns_record']"]
    Example2["map[RelationType][]AssetType"]
    Example3a["BasicDNSRelation → [FQDN, IPAddress]"]
    Example3b["PrefDNSRelation → [FQDN]"]
    Example3c["SRVDNSRelation → [FQDN]"]

    Example1 --> Example2
    Example2 --> Example3a
    Example2 --> Example3b
    Example2 --> Example3c

    subgraph "Type Definitions"
        Label["Label: Semantic name<br/>(port, dns_record, location)"]
        RType["RelationType: Enumeration<br/>(BasicDNSRelation, SimpleRelation, etc.)"]
        DTypes["Destination Types: Asset type constants<br/>(FQDN, IPAddress, Organization, etc.)"]
    end

Central Dispatcher: assetTypeRelations Function¶

The assetTypeRelations function serves as the central dispatcher that routes each AssetType to its corresponding relationship map. This function implements a large switch statement covering all 21 asset types.

graph LR
    Input["assetTypeRelations(atype AssetType)"]
    Switch["switch statement<br/>(lines 231-276)"]

    Input --> Switch

    Switch --> Case1["case Account → accountRels"]
    Switch --> Case2["case FQDN → fqdnRels"]
    Switch --> Case3["case IPAddress → ipRels"]
    Switch --> Case4["case Organization → orgRels"]
    Switch --> Case5["case Service → serviceRels"]
    Switch --> Case6["case TLSCertificate → tlscertRels"]
    Switch --> Case7["case URL → urlRels"]
    Switch --> CaseN["...17 total cases..."]
    Switch --> Default["default → nil"]

    Case1 --> Return["Returns:<br/>map[string]map[RelationType][]AssetType"]
    Case2 --> Return
    Case3 --> Return
    Case4 --> Return
    Case5 --> Return
    Case6 --> Return
    Case7 --> Return
    CaseN --> Return

The function returns nil for invalid or unrecognized asset types, enabling safe querying through the public API functions.

Query Functions¶

The relationship taxonomy exposes three public query functions, each serving a distinct use case in the asset discovery and validation workflow.

GetAssetOutgoingRelations¶

Returns all valid relationship labels for a given source asset type. This function is used for discovery workflows where the caller needs to enumerate all possible relationships from a specific asset.

Function Signature: GetAssetOutgoingRelations(subject AssetType) []string

Implementation Pattern: 1. Call assetTypeRelations(subject) to get the relationship map 2. Return nil if the map is nil (invalid asset type) 3. Extract all keys from the map (relationship labels) 4. Return the label slice

sequenceDiagram
    participant Caller
    participant GetOutgoing["GetAssetOutgoingRelations"]
    participant Dispatcher["assetTypeRelations"]

    Caller->>GetOutgoing: GetAssetOutgoingRelations(FQDN)
    GetOutgoing->>Dispatcher: assetTypeRelations(FQDN)
    Dispatcher-->>GetOutgoing: fqdnRels map
    GetOutgoing->>GetOutgoing: Extract keys from map
    GetOutgoing-->>Caller: ["port", "dns_record", "node", "registration"]

Example Results:

GetTransformAssetTypes¶

Returns all valid destination asset types for a given source asset type, relationship label, and relation type. This function is used in data transformation pipelines where the caller needs to determine what asset types can be created from a relationship.

Function Signature: GetTransformAssetTypes(subject AssetType, label string, rtype RelationType) []AssetType

Implementation Pattern: 1. Call assetTypeRelations(subject) to get the relationship map 2. Return nil if the map is nil 3. Convert label to lowercase for case-insensitive matching 4. Look up relations[label][rtype] to get the destination types 5. Deduplicate results using a map 6. Return the deduplicated slice

graph TB
    Input["GetTransformAssetTypes(FQDN, 'dns_record', BasicDNSRelation)"]

    Step1["Call assetTypeRelations(FQDN)"]
    Step2["Get fqdnRels map"]
    Step3["Lowercase label: 'dns_record'"]
    Step4["Lookup fqdnRels['dns_record'][BasicDNSRelation]"]
    Step5["Found: [FQDN, IPAddress]"]
    Step6["Deduplicate (map[AssetType]struct{})"]
    Step7["Return [FQDN, IPAddress]"]

    Input --> Step1
    Step1 --> Step2
    Step2 --> Step3
    Step3 --> Step4
    Step4 --> Step5
    Step5 --> Step6
    Step6 --> Step7

Example Results:

ValidRelationship¶

Returns true if a specific relationship quadruple (source, label, relationType, destination) is valid according to the taxonomy. This is the primary validation function used to enforce relationship integrity before persisting data.

Function Signature: ValidRelationship(src AssetType, label string, rtype RelationType, destination AssetType) bool

Implementation Pattern: 1. Call GetTransformAssetTypes(src, label, rtype) to get allowed destinations 2. Return false if the result is nil 3. Iterate through allowed destination types 4. Return true if destination matches any allowed type 5. Return false if no match found

sequenceDiagram
    participant Client
    participant ValidRel["ValidRelationship"]
    participant GetTransform["GetTransformAssetTypes"]

    Client->>ValidRel: ValidRelationship(FQDN, "port", PortRelation, Service)
    ValidRel->>GetTransform: GetTransformAssetTypes(FQDN, "port", PortRelation)
    GetTransform-->>ValidRel: [Service]
    ValidRel->>ValidRel: Check if Service in [Service]
    ValidRel-->>Client: true

    Client->>ValidRel: ValidRelationship(FQDN, "port", PortRelation, Organization)
    ValidRel->>GetTransform: GetTransformAssetTypes(FQDN, "port", PortRelation)
    GetTransform-->>ValidRel: [Service]
    ValidRel->>ValidRel: Check if Organization in [Service]
    ValidRel-->>Client: false

Usage in Data Pipelines:

Discovery Tool → Create Relationship → ValidRelationship() → Store if valid
                                      ↓
                                   false → Log error, discard

Relationship Maps by Asset Type¶

Each asset type has a dedicated relationship map variable that defines its allowed outgoing relationships. The maps are declared as package-level variables and consumed by the assetTypeRelations dispatcher.

Network Asset Relationships¶

FQDN Relationships¶

The fqdnRels map defines four relationship types for FQDN assets, including the only multi-RelationType relationship in the entire taxonomy (the "dns_record" label).

IPAddress Relationships¶

The ipRels map defines relationships for IP address assets.

Netblock Relationships¶

The netblockRels map defines relationships for IP address blocks.

AutonomousSystem Relationships¶

The autonomousSystemRels map defines AS relationships.

Organizational Asset Relationships¶

Organization Relationships¶

The orgRels map defines the most comprehensive set of relationships for modeling organizational structures.

Person Relationships¶

The personRels map defines relationships for individual persons.

Location Relationships¶

The locationRels map is minimal, allowing only identifier linkage.

Digital Asset Relationships¶

Service Relationships¶

The serviceRels map defines relationships for network services.

TLSCertificate Relationships¶

The tlscertRels map defines the most extensive relationship set (10 labels), reflecting the complexity of X.509 certificate data.

URL Relationships¶

The urlRels map connects URLs to their infrastructure components.

File Relationships¶

The fileRels map defines relationships for file assets.

Financial Asset Relationships¶

Account Relationships¶

The accountRels map defines relationships for digital accounts.

FundsTransfer Relationships¶

The fundsTransferRels map models financial transaction relationships.

Product Asset Relationships¶

Product Relationships¶

The productRels map defines relationships for software/hardware products.

ProductRelease Relationships¶

The productReleaseRels map defines relationships for specific product versions.

Registration Record Relationships¶

DomainRecord Relationships¶

The domainRecordRels map defines WHOIS/RDAP domain registration relationships.

AutnumRecord Relationships¶

The autnumRecordRels map defines AS registration relationships.

IPNetRecord Relationships¶

The ipnetRecordRels map defines IP network registration relationships, sharing the same structure as AutnumRecord.

Identifier Asset Relationships¶

Identifier Relationships¶

The identifierRels map allows identifiers to reference their registration authorities.

ContactRecord Relationships¶

The contactRecordRels map is particularly important because contact records aggregate information from WHOIS/RDAP lookups.

Phone Relationships¶

The phoneRels map defines minimal relationships for phone numbers.

Multi-RelationType Relationships¶

The FQDN asset type contains the only multi-RelationType relationship in the entire taxonomy. The "dns_record" label maps to three different RelationType values, each supporting different destination types:

graph LR
    FQDN["FQDN Asset"]
    Label["Label: 'dns_record'"]

    FQDN --> Label

    Label --> Basic["BasicDNSRelation"]
    Label --> Pref["PrefDNSRelation"]
    Label --> SRV["SRVDNSRelation"]

    Basic --> BasicDest["Destinations: [FQDN, IPAddress]"]
    Pref --> PrefDest["Destinations: [FQDN]"]
    SRV --> SRVDest["Destinations: [FQDN]"]

    BasicDest --> A["A record: FQDN → IPAddress"]
    BasicDest --> AAAA["AAAA record: FQDN → IPAddress"]
    BasicDest --> CNAME["CNAME record: FQDN → FQDN"]
    BasicDest --> NS["NS record: FQDN → FQDN"]

    PrefDest --> MX["MX record: FQDN → FQDN<br/>(includes preference value)"]

    SRVDest --> SRVRecord["SRV record: FQDN → FQDN<br/>(includes priority, weight, port)"]

This design allows DNS record semantics to be preserved while maintaining type safety. For example: - A/AAAA records use BasicDNSRelation and point to IPAddress - CNAME/NS records use BasicDNSRelation and point to FQDN - MX records use PrefDNSRelation and point to FQDN, with an additional preference value in the relation - SRV records use SRVDNSRelation and point to FQDN, with priority, weight, and port metadata

All other relationship labels in the taxonomy map to exactly one RelationType.

Usage Patterns¶

Discovery Workflow Pattern¶

sequenceDiagram
    participant Tool["Discovery Tool<br/>(e.g., Amass)"]
    participant Model["open-asset-model"]
    participant Storage["Storage Layer"]

    Tool->>Model: Create FQDN asset
    Tool->>Model: GetAssetOutgoingRelations(FQDN)
    Model-->>Tool: ["port", "dns_record", "node", "registration"]

    Tool->>Tool: Perform DNS lookup
    Tool->>Model: ValidRelationship(FQDN, "dns_record", BasicDNSRelation, IPAddress)
    Model-->>Tool: true

    Tool->>Model: Create BasicDNSRelation instance
    Tool->>Storage: Store asset and relation

    Tool->>Tool: Perform port scan
    Tool->>Model: ValidRelationship(FQDN, "port", PortRelation, Service)
    Model-->>Tool: true

    Tool->>Model: Create PortRelation instance
    Tool->>Storage: Store asset and relation

Validation Pattern¶

graph TB
    Input["Ingest Relationship Quadruple:<br/>(src, label, relType, dest)"]

    Validate["ValidRelationship(src, label, relType, dest)"]

    Input --> Validate

    Validate --> Valid{Valid?}

    Valid -->|true| Store["Store in Database"]
    Valid -->|false| Log["Log Validation Error"]

    Log --> Discard["Discard Relationship"]

    Store --> Index["Update Graph Indices"]

Type Transformation Pattern¶

Tools use GetTransformAssetTypes to determine what asset types to create when processing relationship data:

graph LR
    Source["Source Asset:<br/>TLSCertificate"]

    Query["GetTransformAssetTypes(<br/>TLSCertificate,<br/>'san_dns_name',<br/>SimpleRelation)"]

    Result["Result: [FQDN]"]

    Transform["Create FQDN assets<br/>from SAN DNS names"]

    Source --> Query
    Query --> Result
    Result --> Transform

Summary Table: Complete Taxonomy Overview¶