Skip to content

Commit dfc2d0e

Browse files
caffixcaffix
committed
getting the first few assets in good shape
1 parent 6f6df1a commit dfc2d0e

File tree

4 files changed

+164
-150
lines changed

4 files changed

+164
-150
lines changed

‎docs/open_asset_model/assets/contact_record.md‎

Lines changed: 47 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,57 @@
1-
# :simple-owasp: Contact
1+
# :simple-owasp: ContactRecord
22

3-
The **Contact** entity, which holds assets such as `Email`, `Location`, and `Phone`, is a critical component of comprehensive **Attack Surface Intelligence**. By organizing these assets alongside discovered attributes and relationships, the [Open Asset Model](https://github.com/owasp-amass/open-asset-model) reveals connections across diverse resources, enabling a holistic understanding of the asset landscape.
3+
The **ContactRecord** asset serves as a connective entity that maintains a reliable audit trail of where contact information was discovered during the *attack surface intelligence* collection process. It plays a critical role in ensuring both flexibility and consistency within the [Open Asset Model](https://github.com/owasp-amass/open-asset-model), as it is uniformly applied wherever contact details are identified—regardless of the specific type of contact information uncovered. Because such information is often found in varied groupings, it's important to preserve the context in which each piece was associated. The **ContactRecord** makes this possible by capturing and storing the discovered contact data alongside its source location, maintaining their relationship within the model.
44

5+
## :material-contacts: ContactRecord Attributes
56

6-
Mirroring the adversary's perspective, the **Amass Engine** traces discovery paths, contextualizes insights at each contact point, and identifies exposures to strengthen situational awareness.
7-
8-
---
9-
10-
## :material-hexagon-multiple: Collection
11-
12-
- **Complete Contact Coverage:** Provides a centralized view of standardized contact asset intelligence across **email**, **location**, and **phone**.
13-
- **Email Insights:** Tracks email connections to link addresses to specific **personnel and operational functions**, offering visibility into business process maturity.
14-
- **Location Details:** Includes specific location information, from physical addresses and building details to region and locality, for **complete geographic context**.
15-
- **Phone Numbers:** Captures the relationships between country codes, extensions, and subscriber **numbers with individuals and organizational** structures.
16-
- **Connected Data:** Traces the contact collection's discovery path to clarify its **origin, validity, and relevance** in investigative and data privacy contexts.
17-
18-
---
19-
20-
!!! Info annotate "OAM Taxonomy"
21-
The diagrams and data tables below outline the properties and incoming relationships for each `Contact Asset` type: `Email`, `Location`, and `Phone`. # (1)!
22-
23-
1. :material-check-decagram: Required fields are denoted in the data tables.
24-
25-
---
26-
27-
## :material-email: Email Address
28-
29-
Email characteristics offer valuable intelligence for profiling and mapping an organization’s internal structure, operational contacts, and network ownership. Analyzing relationships among contact points makes it possible to trace domain ownership, uncover technical support channels, and reveal security response capabilities. This structured email data enriches the understanding of organizational roles and personnel responsibilities, providing a comprehensive view of the asset landscape through an offensive lens.
30-
31-
---
32-
33-
!!! Danger "Email Requirements"
34-
A full email `address`, formatted as a `string`, is required for mapping the related relationships.
7+
| Attributes | Type | Required | Description |
8+
| -------- | ---- | :--------: | ----------- |
9+
| `discovered_at` | string | :material-check-decagram: | Unique URL or path to the contact information |
3510

36-
---
11+
## :material-contacts: ContactRecord Outgoing Relations
3712

38-
``` mermaid
13+
```mermaid
3914
graph TD
40-
Contact[("Contact Assets")]
41-
Email("Email
42-
Properties")
43-
44-
Email ==> Contact
45-
46-
Person["Person"]
47-
Organization["Organization"]
48-
TLSCertificate["Fingerprint"]
49-
Registration["Registration"]
50-
51-
registrationEmail@{ shape: braces, label: "admin_email
52-
tech_email
53-
billing_email
54-
registrant_email
55-
abuse_email"}
56-
57-
personEmail@{ shape: braces, label: "email"}
58-
tlsEmail@{ shape: braces, label: "subject_email_address"}
59-
60-
registrationEmail --> Email
61-
Registration --o registrationEmail
62-
63-
personEmail --> Email
64-
Person --o personEmail
65-
Organization --o personEmail
66-
67-
tlsEmail --> Email
68-
TLSCertificate --o tlsEmail
15+
contact["ContactRecord"]
16+
fqdn["FQDN"]
17+
18+
simple1@{ shape: braces, label: "fqdn"}
19+
contact --o simple1
20+
simple1 --> fqdn
21+
22+
id["Identifier"]
23+
simple2@{ shape: braces, label: "id"}
24+
contact --o simple2
25+
simple2 --> id
26+
27+
org["Organization"]
28+
simple3@{ shape: braces, label: "organization"}
29+
contact --o simple3
30+
simple3 --> org
31+
32+
person["Person"]
33+
simple4@{ shape: braces, label: "person"}
34+
contact --o simple4
35+
simple4 --> person
36+
37+
phone["Phone"]
38+
simple5@{ shape: braces, label: "phone"}
39+
contact --o simple5
40+
simple5 --> phone
41+
42+
url["URL"]
43+
simple6@{ shape: braces, label: "url"}
44+
contact --o simple6
45+
simple6 --> url
6946
```
7047

7148
---
7249

73-
74-
### :material-email: Email Properties
75-
76-
| Property | Type | Required | Description |
77-
| -------- | ---- | :--------: | ----------- |
78-
| `address` | string | :material-check-decagram: | The full email address |
79-
| `local` | string | - | The local part of the email address |
80-
| `domain` | string | - | The part of the address after the @ symbol |
81-
82-
83-
#### Incoming Relationships
84-
85-
| Relationship | Type |
86-
| ------------ | ---- |
87-
| `admin_email` | [`Whois`](#whois) |
88-
| `tech_email` | [`Whois`](#whois) |
89-
| `billing_email` | [`Whois`](#whois) |
90-
| `registrant_email` | [`Whois`](#whois) |
91-
| `email` | [`Person`](#person) |
92-
| `email` | [`Organization`](#organization) |
93-
| `abuse_email` | [`Registrar`](#registrar) |
94-
| `subject_email_address` | [`TLSCertificate`](#tls-certificate) |
95-
96-
---
97-
98-
## :material-map-marker: Location
99-
100-
| Property | Type | Required | Description |
101-
| -------- | ---- | :--------: | ----------- |
102-
| `formatted_address` | string | - | The formatted address |
103-
| `building_number` | string | - | the number of the building at the location |
104-
| `street_name` | string | - | the name of the street at the location |
105-
| `unit` | string | - | the unit number at the location |
106-
| `building` | string | - | the name of the building at the location |
107-
| `town` | string | - | the name town or city at the location |
108-
| `locality` | string | - | the locality at the location |
109-
| `region` | string | - | the name of the region or state at the location |
110-
| `country_code` | string | - | the ISO 3166-1 alpha-2 country code |
111-
| `postal_code` | string | - | the postal code at the location |
112-
113-
114-
#### Incoming Relationships
115-
116-
| Relationship | Type |
117-
| ------------ | ---- |
118-
| `admin_location` | [`Whois`](#whois) |
119-
| `tech_location` | [`Whois`](#whois) |
120-
| `billing_location` | [`Whois`](#whois) |
121-
| `registrant_location` | [`Whois`](#whois) |
122-
| `location` | [`Person`](#person) |
123-
| `location` | [`Organization`](#organization) |
124-
| `subject_state_or_province` | [`TLSCertificate`](#tls-certificate) |
125-
| `subject_locality` | [`TLSCertificate`](#tls-certificate) |
126-
127-
---
128-
129-
## :material-phone: Phone
130-
131-
| Property | Type | Required | Description |
132-
| -------- | ---- | :--------: | ----------- |
133-
| `type` | string | - | The type of phone number |
134-
| `raw` | string | :material-check-decagram: | The raw phone number |
135-
| `e164` | string | - | The E.164 formatted phone number |
136-
| `country_abbrev` | string | - | The ISO 3166-1 alpha-2 country code |
137-
| `country_code` | string | - | The ISO 3166-1 numeric country code |
138-
| `subscriber_number` | string | - | The subscriber number |
139-
| `ext` | string | - | The extension of the phone number |
140-
141-
142-
#### Incoming Relationships
143-
144-
| Relationship | Type |
145-
| ------------ | ---- |
146-
| `admin_phone` | [`Whois`](#whois) |
147-
| `tech_phone` | [`Whois`](#whois) |
148-
| `billing_phone` | [`Whois`](#whois) |
149-
| `registrant_phone` | [`Whois`](#whois) |
150-
| `phone_number` | [`Person`](#person) |
151-
| `phone_number` | [`Organization`](#organization) |
152-
| `abuse_phone` | [`Registrar`](#registrar) |
50+
| Relation Label | Relation Type | Assets | Description |
51+
| :--------------: | :---------------: | :--------------: | :------------ |
52+
| `fqdn` | [`SimpleRelation`](#simple_relation) | [`FQDN`](#fqdn) | Represents a FQDN discovered in the contact information |
53+
| `id` | [`SimpleRelation`](#simple_relation) | [`Identifier`](#identifer) | Represents an ID (e.g. email address) in the contact information |
54+
| `organization` | [`SimpleRelation`](#simple_relation) | [`Organization`](#organization) | Represents an organization name in the contact information |
55+
| `person` | [`SimpleRelation`](#simple_relation) | [`Person`](#person) | Represents a person's name discovered with the contact information |
56+
| `phone` | [`SimpleRelation`](#simple_relation) | [`Phone`](#phone) | Represents a phone number in the contact information |
57+
| `url` | [`SimpleRelation`](#simple_relation) | [`URL`](#url) | Represents an URL discovered in the contact information |

‎docs/open_asset_model/assets/fqdn.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
# :simple-owasp: FQDN
22

3-
The **FQDN**, or **Fully Qualified Domain Name (FQDN)**, asset represents a complete and unambiguous domain name that specifies the exact location of a device or resource within a **Domain Name System (DNS)** namespace on the internet. DNS names are critical components of **open-source intelligence (OSINT)** and a comprehensive **attack surface intelligence** collection process. By organizing these assets alongside discovered attributes and relationships, the [Open Asset Model](https://github.com/owasp-amass/open-asset-model) reveals connections across diverse resources, enabling a holistic understanding of the asset landscape.
4-
5-
---
3+
The *Fully Qualified Domain Name* (**FQDN**) asset represents a complete and unambiguous domain name that precisely identifies the location of a device or resource within the *Domain Name System (DNS)* hierarchy. FQDNs are foundational elements in *open-source intelligence (OSINT)* and are essential to building a thorough *attack surface intelligence* profile. Within the [Open Asset Model](https://github.com/owasp-amass/open-asset-model), these assets are organized along with their associated attributes and relationships, helping to uncover connections between otherwise disparate resources. This structured representation enables a more comprehensive and contextualized view of an organization’s digital footprint.
64

75
## :material-dns: FQDN Attributes
86

@@ -12,7 +10,7 @@ The **FQDN**, or **Fully Qualified Domain Name (FQDN)**, asset represents a comp
1210

1311
## :material-dns: FQDN Outgoing Relations
1412

15-
``` mermaid
13+
```mermaid
1614
graph TD
1715
fqdn1["FQDN (e.g. owasp.org)"]
1816
fqdn2["FQDN (e.g. vpn.owasp.org)"]
@@ -52,7 +50,7 @@ regrel --> domrec
5250
---
5351

5452
| Relation Label | Relation Type | Assets | Description |
55-
| :--------------: | :--------------: | :----------: | :---------- |
53+
| :--------------: | :---------------: | :--------------: | :------------ |
5654
| `dns_record` | [`BasicDNSRelation`](#basic_dns_relation) | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Used for most RR types |
5755
| `dns_record` | [`PrefDNSRelation`](#pref_dns_relation) | [`FQDN`](#fqdn) | Used for RR types that have a preference attribute |
5856
| `dns_record` | [`SRVDNSRelation`](#srv_dns_relation) | [`FQDN`](#fqdn) | Used to support the SRV RR type |

‎docs/open_asset_model/assets/index.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,112 @@
11
# :simple-owasp: `Assets`
2+
3+
In the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model), an asset represents any discrete, observable element in the external environment of an organization that holds security or operational relevance. Assets can range from technical resources like domain names and IP addresses to organizational constructs such as legal entities and brand names. What makes assets central to the model is that they serve as the primary objects of analysis—entities that can be discovered, attributed, linked, enriched, and ultimately assessed for risk. Each asset is uniquely identified, carries contextual metadata such as confidence and source of discovery, and participates in a web of typed relationships that form a dynamic, queryable graph of an organization's external footprint.
4+
5+
## Why *Assets* Are the First‑Class Citizens
6+
7+
In the **Open Asset Model (OAM)**, *assets* are the atomic units of knowledge that describe an organization’s externally observable footprint. Every other class in the model—attributes, properties, relations—exists to enrich or contextualize an asset. By treating *everything discoverable* (from a DNS name to a cloud storage bucket) as an asset, we gain three strategic advantages:
8+
9+
1. **Uniform Vocabulary** – Analysts, tools, and automation pipelines can exchange data without bespoke translation layers.
10+
2. **Composable Reasoning** – Graph analytics, enrichment, and risk scoring can be applied consistently because every node shares a common set of metadata fields (`id`, `confidence`, `source` …).
11+
3. **Auditability** – Each asset retains a pointer to discovery provenance, making it trivial to reproduce findings or trace errors.
12+
13+
## Asset Definition
14+
15+
> **Asset**: *An identifiable object—digital, network, or legal—that an organization owns, operates, or relies on and that can be observed from outside the security perimeter.*
16+
17+
An asset is **not** just a label; it is a self‑contained document that answers three questions:
18+
19+
1. **What is it?**\
20+
A type‑specific schema (e.g., *FQDN*, *TLSCertificate*, *AutonomousSystem*).
21+
2. **Where did it come from?**\
22+
One or more *DiscoveryMethods* with timestamps and collection method.
23+
3. **How certain are we?**\
24+
A *confidence* score that downstream pipelines can use to gate actions.
25+
26+
## Asset Taxonomy (Partial)
27+
28+
| Category | Example Asset Types | Typical Sources |
29+
| ---------------------- | ------------------------------------------------------ | ------------------------------------- |
30+
| **Network & DNS** | `FQDN`, `IPAddress`, `AutonomousSystem`, `Netblock` | DNS enumeration, passive DNS, RDAP |
31+
| **Products & Services** | `Product`, `ProductRelease`, `Service` | DNS, Port scanning, banner grabbing |
32+
| **Organization** | `Organization`, `Account`, `FundsTransfer` | GLEIF, business registries |
33+
| **Identity & Contact** | `ContactRecord`, `Identifier`, `Phone`, `Location` | TLS certs, WHOIS, RDAP, websites |
34+
| **Cryptographic** | `TLSCertificate` | CT logs, public websites |
35+
36+
*This list is intentionally open‑ended; community pull requests routinely add new asset types as technology evolves.*
37+
38+
## Core Asset Attributes
39+
40+
Every asset embeds a minimal yet powerful set of metadata:
41+
42+
```json
43+
type: "FQDN"
44+
value: "login.example.com"
45+
created_at: "2025-06-11"
46+
last_seen: "2025-06-27"
47+
```
48+
49+
Additional attributes are type‑specific—for instance, an `IPAddress` has the **address** field, while an `Organization` stores jurisdiction and registration numbers.
50+
51+
## Relationships: Building the Graph
52+
53+
Assets rarely exist in isolation. The model expresses **typed, directed edges** such as:
54+
55+
- `dns_record` – *FQDN* → *IPAddress*
56+
- `contains` – *Netblock* → *IPAddress*
57+
- `announces` – *AutonomousSystem* → *Netblock*
58+
- `registration` – *Netblock* → *IPNetRecord*
59+
60+
These links turn the asset collection into a searchable **property graph**, enabling path‑finding queries like *“Which IP ranges host domains that roll up to Acme Corp’s legal entities?”*
61+
62+
## Lifecycle in the Discovery Pipeline
63+
64+
```mermaid
65+
flowchart LR
66+
subgraph Discovery Engine
67+
A[Raw OSINT] --> B(Parse & Normalize)
68+
B --> C(Create Asset)
69+
C -->|Deduplicate| D[Graph DB]
70+
D --> E(Enrichment / Risk Scoring)
71+
end
72+
```
73+
74+
1. **Parse & Normalize** – A discovery plugin converts evidence into the canonical asset schema.
75+
2. **Create Asset** – New or updated asset documents are emitted with provenance.
76+
3. **Deduplicate** – The graph layer merges assets sharing the same unique `key`.
77+
4. **Enrichment** – Plugins append properties, such as alternative names, vulnerabilities, etc.
78+
5. **Analytics & Export** – Downstream tools run path queries, generate reports, or feed alerting pipelines.
79+
80+
## Quick Example: From Evidence to Asset
81+
82+
Imagine Amass extracts the email address *security@example.com* from the footer of *www.example.com*:
83+
84+
```text
85+
Source URL: https://www.example.com
86+
Evidence: "Contact us at security@example.com for vulnerabilities."
87+
```
88+
89+
The *web scraper* module produces:
90+
91+
```json
92+
type: "ContactRecord"
93+
discovered_at: "http://www.example.com"
94+
value: "security@example.com"
95+
created_at: "2025-06-28"
96+
last_seen: "2025-06-28"
97+
```
98+
99+
An edge will be created between the **ContactRecord** and **Identifier** containing the email address (security@example.com). Future encounters with the same email address will reference the same asset in the graph.
100+
101+
## Where to Go Next
102+
103+
Take a look at the pages with details for every asset type.
104+
105+
- [Relations](../relations/index.md) – Overview of Relations in the Open Asset Model.
106+
- [Properties](../properties/index.md) - Overview of a Property in the Open Asset Model.
107+
- [Triples](../assetdb/triples.md) – Querying the graph with SPARQL‑inspired triples.
108+
- [Assoc Tool](../framework_tools/assoc.md) – Using the command-line tool that queries the graph.
109+
110+
---
111+
112+
*© 2025 Jeff Foley — Licensed under Apache 2.0.*

‎mkdocs.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ site_description: "In-depth OSINT collection and external attack surface mapping
1010
site_author: OWASP Amass Contributors
1111
remote_branch: gh-pages
1212

13-
#copyright:
13+
#copyright: 2025 Jeff Foley
1414

1515
theme:
1616
name: 'material'
@@ -22,14 +22,14 @@ theme:
2222
- media: '(prefers-color-scheme: light)'
2323
scheme: default
2424
primary: 'black'
25-
accent: 'red'
25+
accent: 'blue'
2626
toggle:
2727
icon: material/toggle-switch
2828
name: Switch to dark mode
2929
- media: '(prefers-color-scheme: dark)'
3030
scheme: slate
3131
primary: 'black'
32-
accent: 'red'
32+
accent: 'blue'
3333
toggle:
3434
icon: material/toggle-switch-off-outline
3535
name: Switch to light mode

0 commit comments

Comments
 (0)