|
1 | | -# :simple-owasp: `Relation` |
| 1 | +# :simple-owasp: SimpleRelation |
2 | 2 |
|
3 | | -The [`relation.go`](https://github.com/owasp-amass/open-asset-model/blob/master/relation.go) implementation is designed to manage complex relationships between various assets in a flexible and extensible way. By specifying the types of relationships that can exist between assets and the **allowed target asset types** for a given source asset type and relationship within the **Open Asset Model**, this file serves as a crucial component for structuring interconnected assets, ensuring data integrity, and implementing consistency in asset intelligence gathering. |
| 3 | +TThe **SimpleRelation** in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) is the most straightforward way to express a connection between two assets. |
4 | 4 |
|
5 | | ---- |
| 5 | +- **Definition:** A `SimpleRelation` signifies a directed relationship from one asset to another, capturing things like `dns_record`, `contains`, or `announces`, without added complexity or metadata. It links one asset (the subject) to another (the object). |
6 | 6 |
|
7 | | -## Interface |
| 7 | +- **Purpose:** It models basic asset interdependencies or associations that are essential for understanding attack surface connectivity. By mapping these simple links, organizations can trace how one asset might depend on or enable another from a security standpoint. |
8 | 8 |
|
9 | | -Similar to the `Asset` interface, `relation.go` defines a `Relation` **interface** that represents the contract all relationship types within the Open Asset Model must implement and ensures a consistent structure for representing connections between assets. |
| 9 | +- **Design Choice:** The model intentionally avoids over-engineering by excluding rich semantics or additional fields like roles, weights, or descriptions in a `SimpleRelation`. For more detailed modeling, other specialized relation types can be used. |
10 | 10 |
|
11 | | -```go |
12 | | -type Relation interface { |
13 | | - Label() string |
14 | | - RelationType() RelationType |
15 | | - JSON() ([]byte, error) |
16 | | -} |
17 | | -``` |
| 11 | +In essence, the `SimpleRelation` is a clean, minimal tool used within the OAM to express direct and uncomplicated connections between assets, helping maintain clarity while capturing essential connectivity information. |
18 | 12 |
|
19 | | -The `Relation` interface consists of the following methods: |
| 13 | +## :material-relation-one-to-one: SimpleRelation Attributes |
20 | 14 |
|
21 | | -- `Label() string`: This method is responsible for returning a **string that describes the specific nature of the relationship** between two assets. For example, a relationship between an `FQDN` and an `IPAddress` with a `"dns_record"` label. |
| 15 | +| Attributes | Type | Required | Description | |
| 16 | +| -------- | ---- | :--------: | ----------- | |
| 17 | +| `label` | string | :material-check-decagram: | The label for the relation between two assets | |
22 | 18 |
|
23 | | -- `RelationType() RelationType`: This method returns the general type or category of the relationship as a `RelationType`. The `RelationType` itself is defined as a string type. |
| 19 | +## :material-relation-one-to-one: SimpleRelation Properties |
24 | 20 |
|
25 | | -- `JSON() ([]byte, error)`: Similar to the `Asset` interface in `asset.go`, this method handles the serialization of the relation's data into JSON format. It returns a byte slice representing the JSON encoding and an error if the serialization fails |
26 | | - |
27 | | -The `relation.go` file defines `RelationType` as a string type. It also declares several constants of `RelationType`, which represent the predefined categories of relationships supported by the model: |
28 | | - |
29 | | -```go |
30 | | - |
31 | | -const ( |
32 | | - BasicDNSRelation RelationType = "BasicDNSRelation" |
33 | | - PortRelation RelationType = "PortRelation" |
34 | | - PrefDNSRelation RelationType = "PrefDNSRelation" |
35 | | - SimpleRelation RelationType = "SimpleRelation" |
36 | | - SRVDNSRelation RelationType = "SRVDNSRelation" |
37 | | -) |
38 | | -``` |
39 | | - |
40 | | -These constants provide a standardized enumeration for classifying relationships between assets. |
41 | | - |
42 | | ---- |
43 | | - |
44 | | -## Variable |
45 | | - |
46 | | -Complementing the `RelationType` constants is the `RelationList` variable: |
47 | | - |
48 | | -```go |
49 | | - |
50 | | -var RelationList = []RelationType{ |
51 | | - BasicDNSRelation, |
52 | | - PortRelation, |
53 | | - PrefDNSRelation, |
54 | | - SimpleRelation, |
55 | | - SRVDNSRelation, |
56 | | -} |
57 | | -``` |
58 | | - |
59 | | -This variable is a slice containing all the defined `RelationType` constants. It serves as a centralized registry of all supported relationship types within the Open Asset Model. |
60 | | - |
61 | | ---- |
62 | | - |
63 | | -## Asset Type Relationship Maps |
64 | | - |
65 | | -A significant aspect of `relation.go` is the definition of **maps that specify the permitted outgoing relationships for each** `AssetType` defined in `asset.go`. These maps, such as `accountRels`, `fqdnRels`, and others, are structured to define: |
66 | | - |
67 | | -- The label of the relationship (e.g., `"id"`, `"user"`, `"dns_record"`). |
68 | | - |
69 | | -- The `RelationType` of the relationship (e.g., `SimpleRelation`, `BasicDNSRelation`, `PortRelation`). |
70 | | - |
71 | | -- A slice of `AssetType`(s) that can be the target of this relationship. |
72 | | - |
73 | | -For instance, the `fqdnRels` map defines the allowed outgoing relationships for the `FQDN` asset type and includes relationships like `"port"` of type `PortRelation` targeting `Service` assets, and `"dns_record"` of type `BasicDNSRelation`, `PrefDNSRelation`, and `SRVDNSRelation` targeting `FQDN` or `IPAddress` assets. |
74 | | - |
75 | | -These maps are crucial for defining the **taxonomy of relationships** within the Open Asset Model, outlining which asset types can be connected and the nature of those connections. |
76 | | - |
77 | | ---- |
78 | | - |
79 | | -## Helper Functions |
80 | | - |
81 | | -`relation.go` also includes several helper functions that facilitate the management and validation of relationships: |
82 | | - |
83 | | -- `GetAssetOutgoingRelations(subject AssetType) []string`: This function takes an `AssetType` as input and returns a slice of strings representing the labels of the relations that can originate from this asset type. It retrieves this information from the asset type relationship maps. |
84 | | - |
85 | | -- `GetTransformAssetTypes(subject AssetType, label string, rtype RelationType) []AssetType`: This function, given a subject `AssetType`, a relationship label, and a `RelationType`, returns a slice of `AssetTypes` **that can be the target of such a relationship**. It consults the relevant asset type relationship map to determine the valid target asset types. |
86 | | - |
87 | | -- `assetTypeRelations(atype AssetType) map[string]map[RelationType][]AssetType`: This internal function takes an `AssetType` and returns the **corresponding relationship map** defined in the file (e.g., returns `fqdnRels` if the input is `FQDN`). |
88 | | - |
89 | | -- `ValidRelationship(src AssetType, label string, rtype RelationType, destination AssetType) bool`: This function checks if a **proposed relationship** from a source `AssetType` to a destination `AssetType` with a given label and `RelationType` is valid according to the defined relationship maps. It utilizes `GetTransformAssetTypes` to determine if the destination `AssetType` is permitted for the given source, label, and relation type. |
90 | | - |
91 | | ---- |
92 | | - |
93 | | -## Summary |
94 | | - |
95 | | -The `relation.go` file is fundamental to the Open Asset Model. It defines the `Relation` **interface**, the `RelationType`, and the permissible relationships between different `AssetTypes` through a series of maps and helper functions. By establishing these rules, the Open Asset Model can effectively represent the interconnectedness of assets within an organization's attack surface. This structured approach allows for a more comprehensive and accurate understanding of potential attack vectors. |
96 | | - |
97 | | ---- |
| 21 | +| Property Type | Property Name | Description | |
| 22 | +| :--------------: | :---------------: | :------------ | |
| 23 | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | |
| 24 | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SimpleRelation | |
0 commit comments