From c7c55ec737d3256b7b53c2204e71f53fa5e3d440 Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 26 Jun 2025 01:30:44 -0400 Subject: [PATCH 01/45] fix --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 735637a..3ef4f04 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,7 +39,7 @@ Install the Amass swiss army knife executable in your preferred environment. #### Prerequisites -- **Golang:** Intall an up-to-date version of Go on your system. You can download it from the [Go Official Website](https://go.dev). +- **Golang:** Install an up-to-date version of Go on your system. You can download it from the [Go Official Website](https://go.dev). #### Perform the build and installation process From 52dfe74ab41f46ae45d182fdd578c33bb9434def Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 26 Jun 2025 21:20:52 -0400 Subject: [PATCH 02/45] moved things around --- docs/open_asset_model/{ => assets}/account.md | 0 docs/open_asset_model/{contact.md => assets/contact_record.md} | 0 .../open_asset_model/{registration.md => assets/domain_record.md} | 0 docs/open_asset_model/{ => assets}/file.md | 0 docs/open_asset_model/{certificate.md => assets/fqdn.md} | 0 docs/open_asset_model/{dns.md => assets/funds_transfer.md} | 0 docs/open_asset_model/{ => assets}/identifier.md | 0 docs/open_asset_model/{domain.md => assets/ip_address.md} | 0 docs/open_asset_model/{ => assets}/organization.md | 0 docs/open_asset_model/{people.md => assets/person.md} | 0 docs/open_asset_model/{financial.md => assets/product.md} | 0 docs/open_asset_model/{network.md => assets/tls_certificate.md} | 0 docs/open_asset_model/{ => assets}/url.md | 0 docs/open_asset_model/platform.md | 0 .../{property.md => properties/source_property.md} | 0 .../{relation.md => relations/simple_relation.md} | 0 16 files changed, 0 insertions(+), 0 deletions(-) rename docs/open_asset_model/{ => assets}/account.md (100%) rename docs/open_asset_model/{contact.md => assets/contact_record.md} (100%) rename docs/open_asset_model/{registration.md => assets/domain_record.md} (100%) rename docs/open_asset_model/{ => assets}/file.md (100%) rename docs/open_asset_model/{certificate.md => assets/fqdn.md} (100%) rename docs/open_asset_model/{dns.md => assets/funds_transfer.md} (100%) rename docs/open_asset_model/{ => assets}/identifier.md (100%) rename docs/open_asset_model/{domain.md => assets/ip_address.md} (100%) rename docs/open_asset_model/{ => assets}/organization.md (100%) rename docs/open_asset_model/{people.md => assets/person.md} (100%) rename docs/open_asset_model/{financial.md => assets/product.md} (100%) rename docs/open_asset_model/{network.md => assets/tls_certificate.md} (100%) rename docs/open_asset_model/{ => assets}/url.md (100%) delete mode 100644 docs/open_asset_model/platform.md rename docs/open_asset_model/{property.md => properties/source_property.md} (100%) rename docs/open_asset_model/{relation.md => relations/simple_relation.md} (100%) diff --git a/docs/open_asset_model/account.md b/docs/open_asset_model/assets/account.md similarity index 100% rename from docs/open_asset_model/account.md rename to docs/open_asset_model/assets/account.md diff --git a/docs/open_asset_model/contact.md b/docs/open_asset_model/assets/contact_record.md similarity index 100% rename from docs/open_asset_model/contact.md rename to docs/open_asset_model/assets/contact_record.md diff --git a/docs/open_asset_model/registration.md b/docs/open_asset_model/assets/domain_record.md similarity index 100% rename from docs/open_asset_model/registration.md rename to docs/open_asset_model/assets/domain_record.md diff --git a/docs/open_asset_model/file.md b/docs/open_asset_model/assets/file.md similarity index 100% rename from docs/open_asset_model/file.md rename to docs/open_asset_model/assets/file.md diff --git a/docs/open_asset_model/certificate.md b/docs/open_asset_model/assets/fqdn.md similarity index 100% rename from docs/open_asset_model/certificate.md rename to docs/open_asset_model/assets/fqdn.md diff --git a/docs/open_asset_model/dns.md b/docs/open_asset_model/assets/funds_transfer.md similarity index 100% rename from docs/open_asset_model/dns.md rename to docs/open_asset_model/assets/funds_transfer.md diff --git a/docs/open_asset_model/identifier.md b/docs/open_asset_model/assets/identifier.md similarity index 100% rename from docs/open_asset_model/identifier.md rename to docs/open_asset_model/assets/identifier.md diff --git a/docs/open_asset_model/domain.md b/docs/open_asset_model/assets/ip_address.md similarity index 100% rename from docs/open_asset_model/domain.md rename to docs/open_asset_model/assets/ip_address.md diff --git a/docs/open_asset_model/organization.md b/docs/open_asset_model/assets/organization.md similarity index 100% rename from docs/open_asset_model/organization.md rename to docs/open_asset_model/assets/organization.md diff --git a/docs/open_asset_model/people.md b/docs/open_asset_model/assets/person.md similarity index 100% rename from docs/open_asset_model/people.md rename to docs/open_asset_model/assets/person.md diff --git a/docs/open_asset_model/financial.md b/docs/open_asset_model/assets/product.md similarity index 100% rename from docs/open_asset_model/financial.md rename to docs/open_asset_model/assets/product.md diff --git a/docs/open_asset_model/network.md b/docs/open_asset_model/assets/tls_certificate.md similarity index 100% rename from docs/open_asset_model/network.md rename to docs/open_asset_model/assets/tls_certificate.md diff --git a/docs/open_asset_model/url.md b/docs/open_asset_model/assets/url.md similarity index 100% rename from docs/open_asset_model/url.md rename to docs/open_asset_model/assets/url.md diff --git a/docs/open_asset_model/platform.md b/docs/open_asset_model/platform.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/open_asset_model/property.md b/docs/open_asset_model/properties/source_property.md similarity index 100% rename from docs/open_asset_model/property.md rename to docs/open_asset_model/properties/source_property.md diff --git a/docs/open_asset_model/relation.md b/docs/open_asset_model/relations/simple_relation.md similarity index 100% rename from docs/open_asset_model/relation.md rename to docs/open_asset_model/relations/simple_relation.md From ede6f6f6eb0433849b804dd7ccee6d266f4c15b8 Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 26 Jun 2025 22:11:05 -0400 Subject: [PATCH 03/45] fixed the page tree --- docs/open_asset_model/relations/relation.md | 0 mkdocs.yml | 40 +++++++++++---------- 2 files changed, 22 insertions(+), 18 deletions(-) create mode 100644 docs/open_asset_model/relations/relation.md diff --git a/docs/open_asset_model/relations/relation.md b/docs/open_asset_model/relations/relation.md new file mode 100644 index 0000000..e69de29 diff --git a/mkdocs.yml b/mkdocs.yml index 282d7b6..96f3ca7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,7 +3,7 @@ # mkdocs gh-deploy site_name: OWASP Amass -site_url: https://51nk0r5w1m.github.io/docs/ +site_url: https://owasp-amass.github.io/docs/ repo_name: OWASP Amass repo_url: https://github.com/owasp-amass/amass site_description: "In-depth OSINT collection and external attack surface mapping " @@ -117,26 +117,30 @@ nav: - Getting Started: index.md - Open Asset Model: - Open Asset Model: open_asset_model/index.md - - Asset: open_asset_model/asset.md - - Relation: open_asset_model/relation.md - - Property: open_asset_model/property.md - - Account: open_asset_model/account.md - - Certificate: open_asset_model/certificate.md - - Contact: open_asset_model/contact.md - - DNS: open_asset_model/dns.md - - File: open_asset_model/file.md - - Financial: open_asset_model/financial.md - - Identifier: open_asset_model/identifier.md - - Network: open_asset_model/network.md - - Organization: open_asset_model/organization.md - - People: open_asset_model/people.md - - Platform: open_asset_model/platform.md - - Registration: open_asset_model/registration.md - - URL: open_asset_model/url.md + - Assets: + - Assets: open_asset_model/assets/asset.md + - Account: open_asset_model/assets/account.md + - Contact Record: open_asset_model/assets/contact.md + - Domain Record: open_asset_model/assets/domain_record.md + - File: open_asset_model/assets/file.md + - FQDN: open_asset_model/assets/fqdn.md + - Funds Transfer: open_asset_model/assets/funds_transfer.md + - Identifier: open_asset_model/assets/identifier.md + - IP Address: open_asset_model/assets/ip_address.md + - Organization: open_asset_model/assets/organization.md + - Person: open_asset_model/assets/person.md + - Product: open_asset_model/assets/product.md + - TLS Certificate: open_asset_model/assets/tls_certificate.md + - URL: open_asset_model/assets/url.md + - Relations: + - Relations: open_asset_model/relations/relation.md + - Simple Relation: open_asset_model/relations/simple_relation.md + - Properties: + - Properties: open_asset_model/properties/property.md + - Source Property: open_asset_model/properties/source_property.md - Configuration: configuration/configuration.md - Data Sources: data_sources/data_sources.md - AssetDB: assetDB/assetDB.md - Dashboards: dashboards/dashboards.md - Change Log: changelog/changelog.md - Contributing: contributing/contributing.md - From aff10bf9054eb162618718d80aee4a083bf2cbbe Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 26 Jun 2025 23:16:06 -0400 Subject: [PATCH 04/45] changes to the page layout --- docs/open_asset_model/asset.md | 102 ----------------- docs/open_asset_model/assets/index.md | 1 + docs/open_asset_model/index.md | 116 +++++--------------- docs/open_asset_model/properties/index.md | 1 + docs/open_asset_model/relations/index.md | 1 + docs/open_asset_model/relations/relation.md | 0 mkdocs.yml | 8 +- 7 files changed, 36 insertions(+), 193 deletions(-) delete mode 100644 docs/open_asset_model/asset.md create mode 100644 docs/open_asset_model/assets/index.md create mode 100644 docs/open_asset_model/properties/index.md create mode 100644 docs/open_asset_model/relations/index.md delete mode 100644 docs/open_asset_model/relations/relation.md diff --git a/docs/open_asset_model/asset.md b/docs/open_asset_model/asset.md deleted file mode 100644 index 7b06417..0000000 --- a/docs/open_asset_model/asset.md +++ /dev/null @@ -1,102 +0,0 @@ -# :simple-owasp: `Asset` - -The [`asset.go`](https://github.com/owasp-amass/open-asset-model/blob/master/asset.go) implementation defines the **`Asset` interface** and the **`AssetType`** within the **Open Asset Model**. The `Asset` interface acts as a blueprint or a unified contract that every type of asset within the Open Asset Model must adhere. It provides a standardized way to represent, interact, manage, and process various digital and physical assets. This file is fundamental to the model as it **establishes the core structure** for all supported asset types. - ---- - -## Interface - -The `asset.go` file defines the `Asset` **interface**, which serves as a unified contract that all asset types within the Open Asset Model must implement. This ensures consistency when interacting with different assets - -``` go - -type Asset interface { - Key() string - AssetType() AssetType - JSON() ([]byte, error) -} - -``` - -The `Asset` interface comprises the following methods: - -- `Key() string`: This method is responsible for returning a **unique identifier** for a specific asset instance. This allows for consistent identification and tracking of individual assets. - -- `AssetType() AssetType`: This method returns the type of the asset as a value of the `AssetType`. This enables categorization and specific handling of different asset types within the model. `AssetType` is defined as a simple string type. - -- `JSON() ([]byte, error)`: This method handles the **serialization of the asset's data into a JSON** format. It returns a byte slice representing the JSON encoding of the asset and an error if the serialization fails. This facilitates easy **data interchange** across APIs and databases. - ---- - -## Enumerations - -The `AssetType` is defined as a string alias, ensuring type safety and consistency within the model. The `asset.go` file enumerates a comprehensive list of currently supported asset types as constants of the `AssetType`: - -```go -const ( - Account AssetType = "Account" - AutnumRecord AssetType = "AutnumRecord" - AutonomousSystem AssetType = "AutonomousSystem" - ContactRecord AssetType = "ContactRecord" - DomainRecord AssetType = "DomainRecord" - File AssetType = "File" - FQDN AssetType = "FQDN" - FundsTransfer AssetType = "FundsTransfer" - Identifier AssetType = "Identifier" - IPAddress AssetType = "IPAddress" - IPNetRecord AssetType = "IPNetRecord" - Location AssetType = "Location" - Netblock AssetType = "Netblock" - Organization AssetType = "Organization" - Person AssetType = "Person" - Phone AssetType = "Phone" - Product AssetType = "Product" - ProductRelease AssetType = "ProductRelease" - Service AssetType = "Service" - TLSCertificate AssetType = "TLSCertificate" - URL AssetType = "URL" -) -``` - -These constants represent different categories of assets within an organization's attack surface inventory. The string value of each constant directly represents the specific asset type. - ---- - -## Variable - -Complementing the `AssetType` constants, the `asset.go` file declares a variable `AssetList`: - -``` go -var AssetList = []AssetType{ - Account, AutnumRecord, AutonomousSystem, ContactRecord, DomainRecord, File, FQDN, FundsTransfer, - Identifier, IPAddress, IPNetRecord, Location, Netblock, Organization, Person, Phone, Product, - ProductRelease, Service, TLSCertificate, URL, -} -``` - -This variable is a slice containing all the defined `AssetType` constants. It serves as a centralized registry of all supported asset types. The `AssetList` provides a convenient way to access and iterate over all the predefined asset types handled by the model and can be used for validating if a given string represents a valid `AssetType`. -T - -## `AssetType` vs `AssetList` - -- `AssetType` is the definition of the type itself, a string used to categorize assets. It also serves as the type for the defined constants. - -- `AssetList` is a concrete collection (a slice) containing all the values of the predefined `AssetType` constants. It's an instance that holds all the currently supported asset category identifiers. - -The relationship can be analogized to "color" (`AssetType`) and a list containing "red," "blue," and "green" (`AssetList`). - ---- - -## Summary - -The `asset.go` file is fundamental to the Open Asset Model, ensuring standardized asset representation across various security and reconnaissance applications. Key takeaways include: - -- It defines a structured `Asset` **interface** for consistent asset management. - -- It enumerates **asset types** as constants of `AssetType` to ensure type safety and consistency. - -- It **provides JSON serialization support** through the JSON() method in the `Asset` interface for data interchange. - -- It includes `AssetList` to facilitate asset type validation and iteration. - -By implementing this structured approach, contributors can extend asset handling capabilities, while users can integrate asset intelligence into their security workflows efficiently. diff --git a/docs/open_asset_model/assets/index.md b/docs/open_asset_model/assets/index.md new file mode 100644 index 0000000..f8b59b7 --- /dev/null +++ b/docs/open_asset_model/assets/index.md @@ -0,0 +1 @@ +# :simple-owasp: `Assets` diff --git a/docs/open_asset_model/index.md b/docs/open_asset_model/index.md index 9cd2ffd..4457c39 100644 --- a/docs/open_asset_model/index.md +++ b/docs/open_asset_model/index.md @@ -15,57 +15,7 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a --- -## :material-graph: Graph Structure and Data Model - -=== "[Assets]()" - [:simple-github:](https://github.com/owasp-amass/open-asset-model/blob/master/asset.go) - ``` json - - Account - - Certificate - - Contact - - DNS - - File - - Financial - - Identifier - - Network - - Organization - - People - - Platform - - Registration - - URL - ``` - - -=== "[Relations]()" - [:simple-github:](https://github.com/owasp-amass/open-asset-model/blob/master/relation.go) - - ``` json - - Also referred to as edges. - - Always have a direction to establish asset associations. - - Able to store properties for enriched data analysis. - - Explicit naming convention improves query performance. - - Enable graph traversal to uncover asset associations. - - Define structured links between discovered assets. - - Facilitate discovery of infrastructure dependencies. - - Support queries that reveal attack surface risks. - - Allow efficient correlation of connected entities. - ``` - - -=== "[Properties]()" - [:simple-github:](https://github.com/owasp-amass/open-asset-model/blob/master/property.go) - - ``` json - - Store metadata for discovered assets and their relationships. - - Attach structured data to entities and relationships. - - Standardize attributes like timestamps and source IDs. - - Enable querying and filtering of asset metadata. - - Support enrichment with additional asset details. - - Provide a flexible structure across asset types. - ``` - - -### Explore each asset type and their distinct relationships: +## :material-graph: Explore OAM Asset Types --- @@ -79,34 +29,36 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a Collect usernames, account types, and related attributes to track exposed user accounts - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/account/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/account/) -- :material-file-certificate-outline:{ .lg .middle } __Certificate__ +- :material-registered-trademark:{ .lg .middle } __Domain Record__ --- - Gather SSL/TLS certificate details, issuers, and expiration dates for asset verification + + Gather domain insights, including Whois and registrar details + + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/domain_record/) - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/certificate/) -- :material-comment-outline:{ .lg .middle } __Contact__ +- :material-comment-outline:{ .lg .middle } __Contact Record__ --- Link email addresses, phone numbers, and locations to discovered entities - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/contact/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/contact_record/) -- :material-dns:{ .lg .middle } __DNS__ +- :material-dns:{ .lg .middle } __FQDN__ --- Record domain resolutions, DNS records, and associated metadata - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/dns/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/fqdn/) - :material-file-find:{ .lg .middle } __File__ @@ -115,16 +67,16 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a Capture file names and hashes to analyze digital artifacts - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/file/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/file/) -- :material-bank:{ .lg .middle } __Financial__ +- :material-bank:{ .lg .middle } __Funds Transfer__ --- Identify bank accounts, payment systems, and transaction details - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/financial/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/funds_transfer/) - :material-id-card:{ .lg .middle } __Identifier__ @@ -133,16 +85,16 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a Track unique IDs, references, or numerical values - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/identifier/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/identifier/) -- :material-router:{ .lg .middle } __Network__ +- :material-router:{ .lg .middle } __IP Address__ --- Discover IPs, subnets, and routing structures to uncover key infrastructure - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/network/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/ip_address/) - :material-office-building-marker:{ .lg .middle } __Organization__ @@ -151,35 +103,37 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a Uncover entity designations, locations, and operational details to expose connections - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/organization/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/organization/) -- :material-account-outline:{ .lg .middle } __People__ +- :material-account-outline:{ .lg .middle } __Person__ --- Collect names, locations, and attributes to build individual profiles - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/people/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/person/) + -- :material-apps:{ .lg .middle } __Platform__ +- :material-apps:{ .lg .middle } __Product__ --- Identify online services, cloud providers, and software ecosystems - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/platform/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/product/) -- :material-registered-trademark:{ .lg .middle } __Registration__ + +- :material-file-certificate-outline:{ .lg .middle } __TLS Certificate__ --- - - Gather domain insights, including Whois and registrar details + Gather SSL/TLS certificate details, issuers, and expiration dates for asset verification + + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/tls_certificate/) - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/registration/) - :material-web-refresh:{ .lg .middle } __URL__ @@ -188,18 +142,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a Log web addresses and associated content to track online presence - [:octicons-arrow-right-24: Learn more](https://51nk0r5w1m.github.io/docs/open-asset-model/url/) + [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/url/) - - - - - - - - - - - - diff --git a/docs/open_asset_model/properties/index.md b/docs/open_asset_model/properties/index.md new file mode 100644 index 0000000..3e47632 --- /dev/null +++ b/docs/open_asset_model/properties/index.md @@ -0,0 +1 @@ +# :simple-owasp: `Properties` diff --git a/docs/open_asset_model/relations/index.md b/docs/open_asset_model/relations/index.md new file mode 100644 index 0000000..c35b34b --- /dev/null +++ b/docs/open_asset_model/relations/index.md @@ -0,0 +1 @@ +# :simple-owasp: `Relations` diff --git a/docs/open_asset_model/relations/relation.md b/docs/open_asset_model/relations/relation.md deleted file mode 100644 index e69de29..0000000 diff --git a/mkdocs.yml b/mkdocs.yml index 96f3ca7..2de635d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,9 +118,9 @@ nav: - Open Asset Model: - Open Asset Model: open_asset_model/index.md - Assets: - - Assets: open_asset_model/assets/asset.md + - Assets: open_asset_model/assets/index.md - Account: open_asset_model/assets/account.md - - Contact Record: open_asset_model/assets/contact.md + - Contact Record: open_asset_model/assets/contact_record.md - Domain Record: open_asset_model/assets/domain_record.md - File: open_asset_model/assets/file.md - FQDN: open_asset_model/assets/fqdn.md @@ -133,10 +133,10 @@ nav: - TLS Certificate: open_asset_model/assets/tls_certificate.md - URL: open_asset_model/assets/url.md - Relations: - - Relations: open_asset_model/relations/relation.md + - Relations: open_asset_model/relations/index.md - Simple Relation: open_asset_model/relations/simple_relation.md - Properties: - - Properties: open_asset_model/properties/property.md + - Properties: open_asset_model/properties/index.md - Source Property: open_asset_model/properties/source_property.md - Configuration: configuration/configuration.md - Data Sources: data_sources/data_sources.md From 4bc8548c91e306f075796eba56d70a3a914d9add Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 27 Jun 2025 18:20:50 -0400 Subject: [PATCH 05/45] initial update to the content --- docs/open_asset_model/assets/fqdn.md | 61 ++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index e69de29..1c7b70e 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -0,0 +1,61 @@ +# :simple-owasp: FQDN + +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. + +--- + +## :material-dns: FQDN Attributes + +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `name` | string | :material-check-decagram: | Unique fully qualified domain name (e.g. www.example.com) | + +--- + +## :material-dns: FQDN Outgoing Relations + +``` mermaid +graph TD +fqdn1["FQDN (e.g. example.com)"] +fqdn2["FQDN (e.g. www.example.com)"] +nodeRel@{ shape: braces, label: "node"} +fqdn1 --o nodeRel +nodeRel --> fqdn2 + +ipaddr["IP Address"] +basicdns1@{ shape: braces, label: "dns_record"} +basicdns2@{ shape: braces, label: "dns_record"} +fqdn1 --o basicdns1 +basicdns1 --> ipaddr +fqdn2 --o basicdns2 +basicdns2 --> ipaddr + +fqdn3["FQDN (e.g. send.example.com)] +prefdns@{ shape: braces, label: "dns_record"} +fqdn1 --o prefdns +prefdns --> fqdn3 + +fqdn4["FQDN (e.g. _sip._tcp.example.com)] +srvdns@{ shape: braces, label: "dns_record"} +fqdn4 --o srvdns +srvdns --> fqdn1 + +service["Service"] +port@{ shape: braces, label: "port"} +fqdn2 --o port +port --> service + +domrec["Domain Record"] +regrel@{ shape: braces, label: "registration"} +fqdn1 --o regrel +regrel --> domrec +``` + +| Relation Label | Relation Type | Assets | Description | +| ------------ | ------------ | ------------ | ------------ | +| `dns_record` | [`BasicDNSRelation`](#basic_dns_relation) | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Used for most RR types | +| `dns_record` | [`PrefDNSRelation`](#pref_dns_relation) | [`FQDN`](#fqdn) | Used for RR types that have a preference attribute | +| `dns_record` | [`SRVDNSRelation`](#srv_dns_relation) | [`FQDN`](#fqdn) | Used to support the SRV RR type | +| `node` | [`SimpleRelation`](#simple_relation) | [`FQDN`](#fqdn) | Links a DNS zone apex to nodes within the zone | +| `port` | [`PortRelation`](#port_relation) | [`Service`](#service) | Represents a port at the FQDN with a responding service | +| `registration` | [`SimpleRelation`](#simple_relation) | [`DomainRecord`](#domain_record) | Links a root domain to registration data | From fb8b8859d8b711b95b694e3c523a4635798b36df Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 27 Jun 2025 18:25:08 -0400 Subject: [PATCH 06/45] fixes --- docs/open_asset_model/assets/fqdn.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 1c7b70e..fc3e847 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -30,12 +30,12 @@ basicdns1 --> ipaddr fqdn2 --o basicdns2 basicdns2 --> ipaddr -fqdn3["FQDN (e.g. send.example.com)] +fqdn3["FQDN (e.g. send.example.com)"] prefdns@{ shape: braces, label: "dns_record"} fqdn1 --o prefdns prefdns --> fqdn3 -fqdn4["FQDN (e.g. _sip._tcp.example.com)] +fqdn4["FQDN (e.g. _sip._tcp.example.com)"] srvdns@{ shape: braces, label: "dns_record"} fqdn4 --o srvdns srvdns --> fqdn1 @@ -52,7 +52,7 @@ regrel --> domrec ``` | Relation Label | Relation Type | Assets | Description | -| ------------ | ------------ | ------------ | ------------ | +| -------------- | -------------- | -------------- | -------------- | | `dns_record` | [`BasicDNSRelation`](#basic_dns_relation) | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Used for most RR types | | `dns_record` | [`PrefDNSRelation`](#pref_dns_relation) | [`FQDN`](#fqdn) | Used for RR types that have a preference attribute | | `dns_record` | [`SRVDNSRelation`](#srv_dns_relation) | [`FQDN`](#fqdn) | Used to support the SRV RR type | From 6f6df1a28f1391a81903fac77c774fdc439fd37b Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 27 Jun 2025 20:32:46 -0400 Subject: [PATCH 07/45] update --- docs/open_asset_model/assets/fqdn.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index fc3e847..b6fed53 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -10,14 +10,12 @@ The **FQDN**, or **Fully Qualified Domain Name (FQDN)**, asset represents a comp | -------- | ---- | :--------: | ----------- | | `name` | string | :material-check-decagram: | Unique fully qualified domain name (e.g. www.example.com) | ---- - ## :material-dns: FQDN Outgoing Relations ``` mermaid graph TD -fqdn1["FQDN (e.g. example.com)"] -fqdn2["FQDN (e.g. www.example.com)"] +fqdn1["FQDN (e.g. owasp.org)"] +fqdn2["FQDN (e.g. vpn.owasp.org)"] nodeRel@{ shape: braces, label: "node"} fqdn1 --o nodeRel nodeRel --> fqdn2 @@ -30,12 +28,12 @@ basicdns1 --> ipaddr fqdn2 --o basicdns2 basicdns2 --> ipaddr -fqdn3["FQDN (e.g. send.example.com)"] +fqdn3["FQDN (e.g. send.owasp.org)"] prefdns@{ shape: braces, label: "dns_record"} fqdn1 --o prefdns prefdns --> fqdn3 -fqdn4["FQDN (e.g. _sip._tcp.example.com)"] +fqdn4["FQDN (e.g. _sip._tcp.owasp.org)"] srvdns@{ shape: braces, label: "dns_record"} fqdn4 --o srvdns srvdns --> fqdn1 @@ -51,8 +49,10 @@ fqdn1 --o regrel regrel --> domrec ``` +--- + | Relation Label | Relation Type | Assets | Description | -| -------------- | -------------- | -------------- | -------------- | +| :--------------: | :--------------: | :----------: | :---------- | | `dns_record` | [`BasicDNSRelation`](#basic_dns_relation) | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Used for most RR types | | `dns_record` | [`PrefDNSRelation`](#pref_dns_relation) | [`FQDN`](#fqdn) | Used for RR types that have a preference attribute | | `dns_record` | [`SRVDNSRelation`](#srv_dns_relation) | [`FQDN`](#fqdn) | Used to support the SRV RR type | From dfc2d0e74cc20fd15feed9d78b68c43833944314 Mon Sep 17 00:00:00 2001 From: caffix Date: Sat, 28 Jun 2025 14:41:46 -0400 Subject: [PATCH 08/45] getting the first few assets in good shape --- .../open_asset_model/assets/contact_record.md | 189 +++++------------- docs/open_asset_model/assets/fqdn.md | 8 +- docs/open_asset_model/assets/index.md | 111 ++++++++++ mkdocs.yml | 6 +- 4 files changed, 164 insertions(+), 150 deletions(-) diff --git a/docs/open_asset_model/assets/contact_record.md b/docs/open_asset_model/assets/contact_record.md index 878efd4..4e3f887 100644 --- a/docs/open_asset_model/assets/contact_record.md +++ b/docs/open_asset_model/assets/contact_record.md @@ -1,152 +1,57 @@ -# :simple-owasp: Contact +# :simple-owasp: ContactRecord -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. +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. +## :material-contacts: ContactRecord Attributes -Mirroring the adversary's perspective, the **Amass Engine** traces discovery paths, contextualizes insights at each contact point, and identifies exposures to strengthen situational awareness. - ---- - -## :material-hexagon-multiple: Collection - -- **Complete Contact Coverage:** Provides a centralized view of standardized contact asset intelligence across **email**, **location**, and **phone**. -- **Email Insights:** Tracks email connections to link addresses to specific **personnel and operational functions**, offering visibility into business process maturity. -- **Location Details:** Includes specific location information, from physical addresses and building details to region and locality, for **complete geographic context**. -- **Phone Numbers:** Captures the relationships between country codes, extensions, and subscriber **numbers with individuals and organizational** structures. -- **Connected Data:** Traces the contact collection's discovery path to clarify its **origin, validity, and relevance** in investigative and data privacy contexts. - ---- - -!!! Info annotate "OAM Taxonomy" - The diagrams and data tables below outline the properties and incoming relationships for each `Contact Asset` type: `Email`, `Location`, and `Phone`. # (1)! - -1. :material-check-decagram: Required fields are denoted in the data tables. - ---- - -## :material-email: Email Address - -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. - ---- - -!!! Danger "Email Requirements" - A full email `address`, formatted as a `string`, is required for mapping the related relationships. +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `discovered_at` | string | :material-check-decagram: | Unique URL or path to the contact information | ---- +## :material-contacts: ContactRecord Outgoing Relations -``` mermaid +```mermaid graph TD -Contact[("Contact Assets")] -Email("Email -Properties") - -Email ==> Contact - -Person["Person"] -Organization["Organization"] -TLSCertificate["Fingerprint"] -Registration["Registration"] - -registrationEmail@{ shape: braces, label: "admin_email -tech_email -billing_email -registrant_email -abuse_email"} - -personEmail@{ shape: braces, label: "email"} -tlsEmail@{ shape: braces, label: "subject_email_address"} - -registrationEmail --> Email -Registration --o registrationEmail - -personEmail --> Email -Person --o personEmail -Organization --o personEmail - -tlsEmail --> Email -TLSCertificate --o tlsEmail +contact["ContactRecord"] +fqdn["FQDN"] + +simple1@{ shape: braces, label: "fqdn"} +contact --o simple1 +simple1 --> fqdn + +id["Identifier"] +simple2@{ shape: braces, label: "id"} +contact --o simple2 +simple2 --> id + +org["Organization"] +simple3@{ shape: braces, label: "organization"} +contact --o simple3 +simple3 --> org + +person["Person"] +simple4@{ shape: braces, label: "person"} +contact --o simple4 +simple4 --> person + +phone["Phone"] +simple5@{ shape: braces, label: "phone"} +contact --o simple5 +simple5 --> phone + +url["URL"] +simple6@{ shape: braces, label: "url"} +contact --o simple6 +simple6 --> url ``` --- - -### :material-email: Email Properties - -| Property | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | -| `address` | string | :material-check-decagram: | The full email address | -| `local` | string | - | The local part of the email address | -| `domain` | string | - | The part of the address after the @ symbol | - - -#### Incoming Relationships - -| Relationship | Type | -| ------------ | ---- | -| `admin_email` | [`Whois`](#whois) | -| `tech_email` | [`Whois`](#whois) | -| `billing_email` | [`Whois`](#whois) | -| `registrant_email` | [`Whois`](#whois) | -| `email` | [`Person`](#person) | -| `email` | [`Organization`](#organization) | -| `abuse_email` | [`Registrar`](#registrar) | -| `subject_email_address` | [`TLSCertificate`](#tls-certificate) | - ---- - -## :material-map-marker: Location - -| Property | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | -| `formatted_address` | string | - | The formatted address | -| `building_number` | string | - | the number of the building at the location | -| `street_name` | string | - | the name of the street at the location | -| `unit` | string | - | the unit number at the location | -| `building` | string | - | the name of the building at the location | -| `town` | string | - | the name town or city at the location | -| `locality` | string | - | the locality at the location | -| `region` | string | - | the name of the region or state at the location | -| `country_code` | string | - | the ISO 3166-1 alpha-2 country code | -| `postal_code` | string | - | the postal code at the location | - - -#### Incoming Relationships - -| Relationship | Type | -| ------------ | ---- | -| `admin_location` | [`Whois`](#whois) | -| `tech_location` | [`Whois`](#whois) | -| `billing_location` | [`Whois`](#whois) | -| `registrant_location` | [`Whois`](#whois) | -| `location` | [`Person`](#person) | -| `location` | [`Organization`](#organization) | -| `subject_state_or_province` | [`TLSCertificate`](#tls-certificate) | -| `subject_locality` | [`TLSCertificate`](#tls-certificate) | - ---- - -## :material-phone: Phone - -| Property | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | -| `type` | string | - | The type of phone number | -| `raw` | string | :material-check-decagram: | The raw phone number | -| `e164` | string | - | The E.164 formatted phone number | -| `country_abbrev` | string | - | The ISO 3166-1 alpha-2 country code | -| `country_code` | string | - | The ISO 3166-1 numeric country code | -| `subscriber_number` | string | - | The subscriber number | -| `ext` | string | - | The extension of the phone number | - - -#### Incoming Relationships - -| Relationship | Type | -| ------------ | ---- | -| `admin_phone` | [`Whois`](#whois) | -| `tech_phone` | [`Whois`](#whois) | -| `billing_phone` | [`Whois`](#whois) | -| `registrant_phone` | [`Whois`](#whois) | -| `phone_number` | [`Person`](#person) | -| `phone_number` | [`Organization`](#organization) | -| `abuse_phone` | [`Registrar`](#registrar) | +| Relation Label | Relation Type | Assets | Description | +| :--------------: | :---------------: | :--------------: | :------------ | +| `fqdn` | [`SimpleRelation`](#simple_relation) | [`FQDN`](#fqdn) | Represents a FQDN discovered in the contact information | +| `id` | [`SimpleRelation`](#simple_relation) | [`Identifier`](#identifer) | Represents an ID (e.g. email address) in the contact information | +| `organization` | [`SimpleRelation`](#simple_relation) | [`Organization`](#organization) | Represents an organization name in the contact information | +| `person` | [`SimpleRelation`](#simple_relation) | [`Person`](#person) | Represents a person's name discovered with the contact information | +| `phone` | [`SimpleRelation`](#simple_relation) | [`Phone`](#phone) | Represents a phone number in the contact information | +| `url` | [`SimpleRelation`](#simple_relation) | [`URL`](#url) | Represents an URL discovered in the contact information | diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index b6fed53..90ab81d 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -1,8 +1,6 @@ # :simple-owasp: FQDN -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. - ---- +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. ## :material-dns: FQDN Attributes @@ -12,7 +10,7 @@ The **FQDN**, or **Fully Qualified Domain Name (FQDN)**, asset represents a comp ## :material-dns: FQDN Outgoing Relations -``` mermaid +```mermaid graph TD fqdn1["FQDN (e.g. owasp.org)"] fqdn2["FQDN (e.g. vpn.owasp.org)"] @@ -52,7 +50,7 @@ regrel --> domrec --- | Relation Label | Relation Type | Assets | Description | -| :--------------: | :--------------: | :----------: | :---------- | +| :--------------: | :---------------: | :--------------: | :------------ | | `dns_record` | [`BasicDNSRelation`](#basic_dns_relation) | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Used for most RR types | | `dns_record` | [`PrefDNSRelation`](#pref_dns_relation) | [`FQDN`](#fqdn) | Used for RR types that have a preference attribute | | `dns_record` | [`SRVDNSRelation`](#srv_dns_relation) | [`FQDN`](#fqdn) | Used to support the SRV RR type | diff --git a/docs/open_asset_model/assets/index.md b/docs/open_asset_model/assets/index.md index f8b59b7..e3d97b3 100644 --- a/docs/open_asset_model/assets/index.md +++ b/docs/open_asset_model/assets/index.md @@ -1 +1,112 @@ # :simple-owasp: `Assets` + +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. + +## Why *Assets* Are the First‑Class Citizens + +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: + +1. **Uniform Vocabulary** – Analysts, tools, and automation pipelines can exchange data without bespoke translation layers. +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` …). +3. **Auditability** – Each asset retains a pointer to discovery provenance, making it trivial to reproduce findings or trace errors. + +## Asset Definition + +> **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.* + +An asset is **not** just a label; it is a self‑contained document that answers three questions: + +1. **What is it?**\ + A type‑specific schema (e.g., *FQDN*, *TLSCertificate*, *AutonomousSystem*). +2. **Where did it come from?**\ + One or more *DiscoveryMethods* with timestamps and collection method. +3. **How certain are we?**\ + A *confidence* score that downstream pipelines can use to gate actions. + +## Asset Taxonomy (Partial) + +| Category | Example Asset Types | Typical Sources | +| ---------------------- | ------------------------------------------------------ | ------------------------------------- | +| **Network & DNS** | `FQDN`, `IPAddress`, `AutonomousSystem`, `Netblock` | DNS enumeration, passive DNS, RDAP | +| **Products & Services** | `Product`, `ProductRelease`, `Service` | DNS, Port scanning, banner grabbing | +| **Organization** | `Organization`, `Account`, `FundsTransfer` | GLEIF, business registries | +| **Identity & Contact** | `ContactRecord`, `Identifier`, `Phone`, `Location` | TLS certs, WHOIS, RDAP, websites | +| **Cryptographic** | `TLSCertificate` | CT logs, public websites | + +*This list is intentionally open‑ended; community pull requests routinely add new asset types as technology evolves.* + +## Core Asset Attributes + +Every asset embeds a minimal yet powerful set of metadata: + +```json +type: "FQDN" +value: "login.example.com" +created_at: "2025-06-11" +last_seen: "2025-06-27" +``` + +Additional attributes are type‑specific—for instance, an `IPAddress` has the **address** field, while an `Organization` stores jurisdiction and registration numbers. + +## Relationships: Building the Graph + +Assets rarely exist in isolation. The model expresses **typed, directed edges** such as: + +- `dns_record` – *FQDN* → *IPAddress* +- `contains` – *Netblock* → *IPAddress* +- `announces` – *AutonomousSystem* → *Netblock* +- `registration` – *Netblock* → *IPNetRecord* + +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?”* + +## Lifecycle in the Discovery Pipeline + +```mermaid +flowchart LR + subgraph Discovery Engine + A[Raw OSINT] --> B(Parse & Normalize) + B --> C(Create Asset) + C -->|Deduplicate| D[Graph DB] + D --> E(Enrichment / Risk Scoring) + end +``` + +1. **Parse & Normalize** – A discovery plugin converts evidence into the canonical asset schema. +2. **Create Asset** – New or updated asset documents are emitted with provenance. +3. **Deduplicate** – The graph layer merges assets sharing the same unique `key`. +4. **Enrichment** – Plugins append properties, such as alternative names, vulnerabilities, etc. +5. **Analytics & Export** – Downstream tools run path queries, generate reports, or feed alerting pipelines. + +## Quick Example: From Evidence to Asset + +Imagine Amass extracts the email address *security@example.com* from the footer of *www.example.com*: + +```text +Source URL: https://www.example.com +Evidence: "Contact us at security@example.com for vulnerabilities." +``` + +The *web scraper* module produces: + +```json +type: "ContactRecord" +discovered_at: "http://www.example.com" +value: "security@example.com" +created_at: "2025-06-28" +last_seen: "2025-06-28" +``` + +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. + +## Where to Go Next + +Take a look at the pages with details for every asset type. + +- [Relations](../relations/index.md) – Overview of Relations in the Open Asset Model. +- [Properties](../properties/index.md) - Overview of a Property in the Open Asset Model. +- [Triples](../assetdb/triples.md) – Querying the graph with SPARQL‑inspired triples. +- [Assoc Tool](../framework_tools/assoc.md) – Using the command-line tool that queries the graph. + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/mkdocs.yml b/mkdocs.yml index 2de635d..c70582a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ site_description: "In-depth OSINT collection and external attack surface mapping site_author: OWASP Amass Contributors remote_branch: gh-pages -#copyright: +#copyright: 2025 Jeff Foley theme: name: 'material' @@ -22,14 +22,14 @@ theme: - media: '(prefers-color-scheme: light)' scheme: default primary: 'black' - accent: 'red' + accent: 'blue' toggle: icon: material/toggle-switch name: Switch to dark mode - media: '(prefers-color-scheme: dark)' scheme: slate primary: 'black' - accent: 'red' + accent: 'blue' toggle: icon: material/toggle-switch-off-outline name: Switch to light mode From 2ac724a2a4bb2a80091be1a6e37e283e57c9bc89 Mon Sep 17 00:00:00 2001 From: caffix Date: Sat, 28 Jun 2025 15:18:24 -0400 Subject: [PATCH 09/45] fixes --- docs/open_asset_model/assets/index.md | 22 ++++++++++------------ mkdocs.yml | 10 +++++----- 2 files changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/open_asset_model/assets/index.md b/docs/open_asset_model/assets/index.md index e3d97b3..307bf09 100644 --- a/docs/open_asset_model/assets/index.md +++ b/docs/open_asset_model/assets/index.md @@ -1,8 +1,8 @@ -# :simple-owasp: `Assets` +# :simple-owasp: Assets 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. -## Why *Assets* Are the First‑Class Citizens +## :material-graph-outline: Why *Assets* Are the First‑Class Citizens 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: @@ -10,7 +10,7 @@ In the **Open Asset Model (OAM)**, *assets* are the atomic units of knowledge th 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` …). 3. **Auditability** – Each asset retains a pointer to discovery provenance, making it trivial to reproduce findings or trace errors. -## Asset Definition +## :material-graph-outline: Asset Definition > **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.* @@ -23,7 +23,7 @@ An asset is **not** just a label; it is a self‑contained document that answers 3. **How certain are we?**\ A *confidence* score that downstream pipelines can use to gate actions. -## Asset Taxonomy (Partial) +## :material-graph-outline: Asset Taxonomy (Partial) | Category | Example Asset Types | Typical Sources | | ---------------------- | ------------------------------------------------------ | ------------------------------------- | @@ -35,20 +35,19 @@ An asset is **not** just a label; it is a self‑contained document that answers *This list is intentionally open‑ended; community pull requests routinely add new asset types as technology evolves.* -## Core Asset Attributes +## :material-graph-outline: Core Asset Attributes Every asset embeds a minimal yet powerful set of metadata: ```json type: "FQDN" -value: "login.example.com" created_at: "2025-06-11" last_seen: "2025-06-27" ``` Additional attributes are type‑specific—for instance, an `IPAddress` has the **address** field, while an `Organization` stores jurisdiction and registration numbers. -## Relationships: Building the Graph +## :material-graph-outline: Relationships: Building the Graph Assets rarely exist in isolation. The model expresses **typed, directed edges** such as: @@ -59,7 +58,7 @@ Assets rarely exist in isolation. The model expresses **typed, directed edges** 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?”* -## Lifecycle in the Discovery Pipeline +## :material-graph-outline: Lifecycle in the Discovery Pipeline ```mermaid flowchart LR @@ -77,7 +76,7 @@ flowchart LR 4. **Enrichment** – Plugins append properties, such as alternative names, vulnerabilities, etc. 5. **Analytics & Export** – Downstream tools run path queries, generate reports, or feed alerting pipelines. -## Quick Example: From Evidence to Asset +## :material-graph-outline: Quick Example: From Evidence to Asset Imagine Amass extracts the email address *security@example.com* from the footer of *www.example.com*: @@ -91,16 +90,15 @@ The *web scraper* module produces: ```json type: "ContactRecord" discovered_at: "http://www.example.com" -value: "security@example.com" created_at: "2025-06-28" last_seen: "2025-06-28" ``` 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. -## Where to Go Next +## :material-graph-outline: Where to Go Next -Take a look at the pages with details for every asset type. +Take a look at the pages where details are provided for each asset type. - [Relations](../relations/index.md) – Overview of Relations in the Open Asset Model. - [Properties](../properties/index.md) - Overview of a Property in the Open Asset Model. diff --git a/mkdocs.yml b/mkdocs.yml index c70582a..b44e0f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,17 +120,17 @@ nav: - Assets: - Assets: open_asset_model/assets/index.md - Account: open_asset_model/assets/account.md - - Contact Record: open_asset_model/assets/contact_record.md - - Domain Record: open_asset_model/assets/domain_record.md + - ContactRecord: open_asset_model/assets/contact_record.md + - DomainRecord: open_asset_model/assets/domain_record.md - File: open_asset_model/assets/file.md - FQDN: open_asset_model/assets/fqdn.md - - Funds Transfer: open_asset_model/assets/funds_transfer.md + - FundsTransfer: open_asset_model/assets/funds_transfer.md - Identifier: open_asset_model/assets/identifier.md - - IP Address: open_asset_model/assets/ip_address.md + - IPAddress: open_asset_model/assets/ip_address.md - Organization: open_asset_model/assets/organization.md - Person: open_asset_model/assets/person.md - Product: open_asset_model/assets/product.md - - TLS Certificate: open_asset_model/assets/tls_certificate.md + - TLSCertificate: open_asset_model/assets/tls_certificate.md - URL: open_asset_model/assets/url.md - Relations: - Relations: open_asset_model/relations/index.md From b959d91765e58cfc4bd58ad24b463f3f3442905b Mon Sep 17 00:00:00 2001 From: caffix Date: Sun, 29 Jun 2025 21:47:00 -0400 Subject: [PATCH 10/45] improving the templates for assets --- .../open_asset_model/assets/contact_record.md | 21 ++++++++++++------ docs/open_asset_model/assets/fqdn.md | 22 +++++++++++++------ 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/open_asset_model/assets/contact_record.md b/docs/open_asset_model/assets/contact_record.md index 4e3f887..5be410d 100644 --- a/docs/open_asset_model/assets/contact_record.md +++ b/docs/open_asset_model/assets/contact_record.md @@ -8,6 +8,13 @@ The **ContactRecord** asset serves as a connective entity that maintains a relia | -------- | ---- | :--------: | ----------- | | `discovered_at` | string | :material-check-decagram: | Unique URL or path to the contact information | +## :material-contacts: ContactRecord Properties + +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried for this ContactRecord | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this ContactRecord | + ## :material-contacts: ContactRecord Outgoing Relations ```mermaid @@ -47,11 +54,11 @@ simple6 --> url --- -| Relation Label | Relation Type | Assets | Description | +| Relation Type | Relation Label | Target Assets | Description | | :--------------: | :---------------: | :--------------: | :------------ | -| `fqdn` | [`SimpleRelation`](#simple_relation) | [`FQDN`](#fqdn) | Represents a FQDN discovered in the contact information | -| `id` | [`SimpleRelation`](#simple_relation) | [`Identifier`](#identifer) | Represents an ID (e.g. email address) in the contact information | -| `organization` | [`SimpleRelation`](#simple_relation) | [`Organization`](#organization) | Represents an organization name in the contact information | -| `person` | [`SimpleRelation`](#simple_relation) | [`Person`](#person) | Represents a person's name discovered with the contact information | -| `phone` | [`SimpleRelation`](#simple_relation) | [`Phone`](#phone) | Represents a phone number in the contact information | -| `url` | [`SimpleRelation`](#simple_relation) | [`URL`](#url) | Represents an URL discovered in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `fqdn` | [`FQDN`](#fqdn) | Represents a FQDN discovered in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](#identifer) | Represents an ID (e.g. email address) in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `organization` | [`Organization`](#organization) | Represents an organization name in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `person` | [`Person`](#person) | Represents a person's name discovered with the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `phone` | [`Phone`](#phone) | Represents a phone number in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `url` | [`URL`](#url) | Represents an URL discovered in the contact information | diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 90ab81d..b301aad 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -8,6 +8,14 @@ The *Fully Qualified Domain Name* (**FQDN**) asset represents a complete and una | -------- | ---- | :--------: | ----------- | | `name` | string | :material-check-decagram: | Unique fully qualified domain name (e.g. www.example.com) | +## :material-dns: FQDN Properties + +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried for this FQDN | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this FQDN | +| [`DNSRecordProperty`](../properties/dns_property.md) | `dns_record` | Represents a DNS record for this FQDN that provides only data | + ## :material-dns: FQDN Outgoing Relations ```mermaid @@ -49,11 +57,11 @@ regrel --> domrec --- -| Relation Label | Relation Type | Assets | Description | +| Relation Type | Relation Label | Target Assets | Description | | :--------------: | :---------------: | :--------------: | :------------ | -| `dns_record` | [`BasicDNSRelation`](#basic_dns_relation) | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Used for most RR types | -| `dns_record` | [`PrefDNSRelation`](#pref_dns_relation) | [`FQDN`](#fqdn) | Used for RR types that have a preference attribute | -| `dns_record` | [`SRVDNSRelation`](#srv_dns_relation) | [`FQDN`](#fqdn) | Used to support the SRV RR type | -| `node` | [`SimpleRelation`](#simple_relation) | [`FQDN`](#fqdn) | Links a DNS zone apex to nodes within the zone | -| `port` | [`PortRelation`](#port_relation) | [`Service`](#service) | Represents a port at the FQDN with a responding service | -| `registration` | [`SimpleRelation`](#simple_relation) | [`DomainRecord`](#domain_record) | Links a root domain to registration data | +| [`BasicDNSRelation`](../relations/basic_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Represents most RR types | +| [`PrefDNSRelation`](../relations/pref_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn) | Utilized for RR types that have a preference attribute | +| [`SRVDNSRelation`](../relations/srv_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn) | Represents the SRV Resource Record type | +| [`SimpleRelation`](../relations/simple_relation.md) | `node` | [`FQDN`](#fqdn) | Links a DNS zone apex to nodes within the zone | +| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](#service) | Represents a port at the FQDN with a responding service | +| [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`DomainRecord`](#domain_record) | Links a root domain to its associated registration data | From c51960847b279b8dd1c215198e550b25f60bec2e Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 30 Jun 2025 01:55:08 -0400 Subject: [PATCH 11/45] initial commit --- .../relations/basic_dns_relation.md | 27 ++++++++++++++ .../relations/port_relation.md | 26 ++++++++++++++ .../relations/pref_dns_relation.md | 28 +++++++++++++++ .../relations/srv_dns_relation.md | 35 +++++++++++++++++++ 4 files changed, 116 insertions(+) create mode 100644 docs/open_asset_model/relations/basic_dns_relation.md create mode 100644 docs/open_asset_model/relations/port_relation.md create mode 100644 docs/open_asset_model/relations/pref_dns_relation.md create mode 100644 docs/open_asset_model/relations/srv_dns_relation.md diff --git a/docs/open_asset_model/relations/basic_dns_relation.md b/docs/open_asset_model/relations/basic_dns_relation.md new file mode 100644 index 0000000..73c6cfd --- /dev/null +++ b/docs/open_asset_model/relations/basic_dns_relation.md @@ -0,0 +1,27 @@ +# :simple-owasp: BasicDNSRelation + +The **BasicDNSRelation** in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a minimal DNS resource record that links a DNS name to either another DNS name or an IP address, using only standard DNS header information. + +- **Definition:** A `BasicDNSRelation` captures DNS records such as A, AAAA, or CNAME that map a hostname to another hostname or IP address. It includes only the DNS header fields and the target reference, without storing extended metadata or record-specific attributes. + +- **Purpose:** This relation type is designed to reflect simple DNS resolution chains within the asset model. It allows mapping how DNS names ultimately resolve to assets or addresses, which is fundamental for understanding how domain names expose infrastructure in an attack surface. + +- **Design Choice:** By limiting the relation to just the DNS header and the resolved name or address, `BasicDNSRelation` avoids the complexity of modeling full DNS behavior (e.g., priorities or DNSSEC). It's intended for lightweight use cases where basic DNS resolution structure is sufficient. + +In summary, `BasicDNSRelation` enables efficient modeling of essential DNS relationships, illustrating how domain names resolve in a minimal, structured format, without the overhead of full DNS record semantics. + +## :material-relation-one-to-one: BasicDNSRelation Attributes + +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `label` | string | :material-check-decagram: | The label for the relation between two assets | +| `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | +| `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | +| `header.ttl` | number | :material-checkbox-blank-circle-outline: | Specifies how long a DNS record should be cached | + +## :material-relation-one-to-one: BasicDNSRelation Properties + +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this BasicDNSRelation | diff --git a/docs/open_asset_model/relations/port_relation.md b/docs/open_asset_model/relations/port_relation.md new file mode 100644 index 0000000..5582e08 --- /dev/null +++ b/docs/open_asset_model/relations/port_relation.md @@ -0,0 +1,26 @@ +# :simple-owasp: PortRelation + +The **PortRelation** in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) captures the association between an asset and a specific network port. + +- **Definition:** A `PortRelation` denotes that a network port (identified by its number and protocol, e.g., TCP/80) is *exposed* or *served by* a given asset. It maps the fact that an asset either offers or uses a service on a designated port. + +- **Purpose:** This relation is essential for modeling network-level exposure of assets. By linking an asset to its port(s), security practitioners can better understand which assets are externally accessible or internally listening, which is critical knowledge for attack surface mapping and vulnerability assessment. + +- **Design Choice:** Unlike `SimpleRelation`, `PortRelation` includes the port identifier and protocol as structured metadata, giving more granularity. It avoids over-specification (e.g. connection counts or performance details) and focuses on capturing *which* port is involved and *how* (via protocol). + +In essence, `PortRelation` adds precise network exposure context to the OAM, letting teams visualize and assess attack vectors related to service ports without unnecessary detail. + +## :material-relation-one-to-one: PortRelation Attributes + +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `label` | string | :material-check-decagram: | The label for the relation between two assets | +| `port_number` | number | :material-check-decagram: | The number assigned to the discovered port | +| `protocol` | string | :material-check-decagram: | The protocol stack of the specified port | + +## :material-relation-one-to-one: PortRelation Properties + +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this PortRelation | diff --git a/docs/open_asset_model/relations/pref_dns_relation.md b/docs/open_asset_model/relations/pref_dns_relation.md new file mode 100644 index 0000000..f0ca5d1 --- /dev/null +++ b/docs/open_asset_model/relations/pref_dns_relation.md @@ -0,0 +1,28 @@ +# :simple-owasp: PrefDNSRelation + +The **PrefDNSRelation** in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) is used to represent DNS resource records that include a **preference** value, such as MX records that define mail server priority for a domain. + +- **Definition:** A `PrefDNSRelation` captures the association between a DNS name and another DNS name or IP address, along with a numeric **preference** value that indicates priority. This is commonly used for records like `MX`, `SRV`, or other types where ordering or selection is influenced by a preference number. + +- **Purpose:** This relation is critical for modeling DNS-based service routing and failover configurations. For example, in an `MX` record, the preference indicates which mail server should be contacted first. Accurately capturing this relationship helps model infrastructure behavior during service discovery, redundancy, and load distribution. + +- **Design Choice:** `PrefDNSRelation` builds on the simpler `BasicDNSRelation` by including a structured `preference` attribute, while still avoiding full record verbosity (e.g., no TTLs, weights, ports, or target service names). This keeps the model lightweight but expressive enough for meaningful DNS prioritization use cases. + +In summary, `PrefDNSRelation` extends basic DNS modeling by introducing priority-aware resolution, enabling the OAM to capture more nuanced DNS relationships where preference order matters. + +## :material-relation-one-to-one: PrefDNSRelation Attributes + +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `label` | string | :material-check-decagram: | The label for the relation between two assets | +| `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | +| `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | +| `header.ttl` | number | :material-checkbox-blank-circle-outline: | Specifies how long a DNS record should be cached | +| `preference` | number | :material-checkbox-blank-circle-outline: | Captures the preference or priority value for this record | + +## :material-relation-one-to-one: PrefDNSRelation Properties + +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this PrefDNSRelation | diff --git a/docs/open_asset_model/relations/srv_dns_relation.md b/docs/open_asset_model/relations/srv_dns_relation.md new file mode 100644 index 0000000..8eeee44 --- /dev/null +++ b/docs/open_asset_model/relations/srv_dns_relation.md @@ -0,0 +1,35 @@ +# :simple-owasp: SRVDNSRelation + +The **SRVDNSRelation** in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) is used to represent DNS SRV (Service) records, which include detailed routing information for locating services such as SIP, XMPP, or LDAP. + +- **Definition:** An `SRVDNSRelation` captures the mapping from a DNS service name (e.g., `_sip._tcp.example.com`) to a target host or IP address, along with structured metadata including **priority**, **weight**, and **port**. These attributes are fundamental to how SRV records guide service resolution. + +- **Purpose:** This relation type is essential for modeling DNS-based service discovery mechanisms where clients need to select among multiple service endpoints based on priority and load-balancing rules. Including all SRV-specific attributes enables accurate representation of how services are discovered and accessed in real-world deployments. + +- **Design Choice:** `SRVDNSRelation` is a more detailed extension of DNS relation types like `BasicDNSRelation` or `PrefDNSRelation`. It includes: + - `priority`: Defines the order in which targets should be attempted (lower is tried first). + - `weight`: Used for load balancing among targets with the same priority. + - `port`: Indicates the port on which the service is running. + +This richer structure allows for nuanced modeling of service behaviors and routing policies that simpler DNS relations cannot capture. + +In summary, `SRVDNSRelation` brings full support for SRV record semantics into the OAM, enabling accurate modeling of service-based resolution patterns that are critical in modern, distributed infrastructure. + +## :material-relation-one-to-one: SRVDNSRelation Attributes + +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `label` | string | :material-check-decagram: | The label for the relation between two assets | +| `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | +| `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | +| `header.ttl` | number | :material-checkbox-blank-circle-outline: | Specifies how long a DNS record should be cached | +| `priority` | number | :material-checkbox-blank-circle-outline: | Captures the priority value for this record | +| `weight` | number | :material-checkbox-blank-circle-outline: | Captures the weight value for this record | +| `port` | number | :material-check-decagram: | Indicates the port on which the service is running | + +## :material-relation-one-to-one: SRVDNSRelation Properties + +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SRVDNSRelation | From a4a766ef920eba8401de95b12f9769cb4451a18c Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 30 Jun 2025 01:55:26 -0400 Subject: [PATCH 12/45] updates --- .../open_asset_model/assets/contact_record.md | 2 +- docs/open_asset_model/assets/fqdn.md | 4 +- .../relations/simple_relation.md | 103 +++--------------- 3 files changed, 18 insertions(+), 91 deletions(-) diff --git a/docs/open_asset_model/assets/contact_record.md b/docs/open_asset_model/assets/contact_record.md index 5be410d..70fcdfe 100644 --- a/docs/open_asset_model/assets/contact_record.md +++ b/docs/open_asset_model/assets/contact_record.md @@ -12,7 +12,7 @@ The **ContactRecord** asset serves as a connective entity that maintains a relia | Property Type | Property Name | Description | | :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried for this ContactRecord | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this ContactRecord | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this ContactRecord | ## :material-contacts: ContactRecord Outgoing Relations diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index b301aad..0bdb133 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -1,6 +1,6 @@ # :simple-owasp: FQDN -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. +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 the organization digital footprint. ## :material-dns: FQDN Attributes @@ -12,7 +12,7 @@ The *Fully Qualified Domain Name* (**FQDN**) asset represents a complete and una | Property Type | Property Name | Description | | :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried for this FQDN | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this FQDN | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this FQDN | | [`DNSRecordProperty`](../properties/dns_property.md) | `dns_record` | Represents a DNS record for this FQDN that provides only data | diff --git a/docs/open_asset_model/relations/simple_relation.md b/docs/open_asset_model/relations/simple_relation.md index 7038a1f..7a22b74 100644 --- a/docs/open_asset_model/relations/simple_relation.md +++ b/docs/open_asset_model/relations/simple_relation.md @@ -1,97 +1,24 @@ -# :simple-owasp: `Relation` +# :simple-owasp: SimpleRelation -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. +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. ---- +- **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). -## Interface +- **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. -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. +- **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. -```go -type Relation interface { - Label() string - RelationType() RelationType - JSON() ([]byte, error) -} -``` +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. -The `Relation` interface consists of the following methods: +## :material-relation-one-to-one: SimpleRelation Attributes -- `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. +| Attributes | Type | Required | Description | +| -------- | ---- | :--------: | ----------- | +| `label` | string | :material-check-decagram: | The label for the relation between two assets | -- `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. +## :material-relation-one-to-one: SimpleRelation Properties -- `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 - -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: - -```go - -const ( - BasicDNSRelation RelationType = "BasicDNSRelation" - PortRelation RelationType = "PortRelation" - PrefDNSRelation RelationType = "PrefDNSRelation" - SimpleRelation RelationType = "SimpleRelation" - SRVDNSRelation RelationType = "SRVDNSRelation" -) -``` - -These constants provide a standardized enumeration for classifying relationships between assets. - ---- - -## Variable - -Complementing the `RelationType` constants is the `RelationList` variable: - -```go - -var RelationList = []RelationType{ - BasicDNSRelation, - PortRelation, - PrefDNSRelation, - SimpleRelation, - SRVDNSRelation, -} -``` - -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. - ---- - -## Asset Type Relationship Maps - -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: - -- The label of the relationship (e.g., `"id"`, `"user"`, `"dns_record"`). - -- The `RelationType` of the relationship (e.g., `SimpleRelation`, `BasicDNSRelation`, `PortRelation`). - -- A slice of `AssetType`(s) that can be the target of this relationship. - -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. - -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. - ---- - -## Helper Functions - -`relation.go` also includes several helper functions that facilitate the management and validation of relationships: - -- `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. - -- `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. - -- `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`). - -- `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. - ---- - -## Summary - -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. - ---- +| Property Type | Property Name | Description | +| :--------------: | :---------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SimpleRelation | From 836366f728465b61d7ef4781a818977033ac300f Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 30 Jun 2025 16:51:34 -0400 Subject: [PATCH 13/45] initial commit --- .../properties/dns_property.md | 24 +++++++++++++++++ .../properties/simple_property.md | 21 +++++++++++++++ .../properties/vuln_property.md | 27 +++++++++++++++++++ 3 files changed, 72 insertions(+) create mode 100644 docs/open_asset_model/properties/dns_property.md create mode 100644 docs/open_asset_model/properties/simple_property.md create mode 100644 docs/open_asset_model/properties/vuln_property.md diff --git a/docs/open_asset_model/properties/dns_property.md b/docs/open_asset_model/properties/dns_property.md new file mode 100644 index 0000000..8cb8500 --- /dev/null +++ b/docs/open_asset_model/properties/dns_property.md @@ -0,0 +1,24 @@ +# :simple-owasp: DNSRecordProperty + +The `DNSRecordProperty` is a structured property type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) used to represent observed Domain Name System (DNS) record data associated with an asset. Unlike a `SimpleProperty`, which encapsulate a single key-value pair, the `DNSRecordProperty` captures a richer snapshot of a specific DNS lookup result, including the record type, value, and TTL. + +DNS information is central to many asset discovery and enumeration processes, and the `DNSRecordProperty` provides a consistent way to describe these findings in the model. It supports representing common record types such as TXT, SOA, HINFO, and others, while also enabling timestamped tracking of when the record was resolved. + +Each `DNSRecordProperty` includes the following components: + +- **Property Name** – The name of the property, which should be `dns_record`. +- **Record Type** – The type of DNS record (e.g., `TXT`, `SOA`, `HINFO`). +- **Record Data** – The result of the DNS resolution (e.g., text string). +- **TTL** – The time-to-live value from the DNS response, indicating how long the result should be considered valid. + +By modeling DNS data with a dedicated property type, `DNSRecordProperty` enables more precise tracking and temporal reasoning around changes in DNS infrastructure. It supports threat hunting, infrastructure correlation, asset ownership validation, and detection of transient or ephemeral DNS configurations. + +## :fontawesome-solid-tags: DNSRecordProperty Attributes + +| Attributes | Type | Required | Description | +| :------------------: | :--------: | :----------: | :------------- | +| `property_name` | string | :material-check-decagram: | The name of the property that should be `dns_record` | +| `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | +| `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | +| `header.ttl` | number | :material-checkbox-blank-circle-outline: | Specifies how long a DNS record should be cached | +| `data` | string | :material-check-decagram: | The value from the data field of the DNS resource record | diff --git a/docs/open_asset_model/properties/simple_property.md b/docs/open_asset_model/properties/simple_property.md new file mode 100644 index 0000000..0d19b37 --- /dev/null +++ b/docs/open_asset_model/properties/simple_property.md @@ -0,0 +1,21 @@ +# :simple-owasp: SimpleProperty + +The `SimpleProperty` is one of the foundational data types used in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) to describe metadata associated with an asset or relation. As its name suggests, a `SimpleProperty` represents a basic key-value pair that conveys a single, scalar piece of information about an asset or relation—such as a name, identifier, timestamp, or descriptive attribute. + +This property type is designed for flexibility and broad applicability. It is not limited to a fixed schema or controlled vocabulary, making it well-suited for capturing diverse details across many different asset and relation types. For example, a `SimpleProperty` might describe the version of a software component, the date a DNS name was last resolved, or a flag indicating whether a host has a JARM fingerprint. + +Each `SimpleProperty` includes the following core components: + +- **Name** – A string that identifies the nature or role of the property (e.g., `last_monitored`). +- **Value** – A string-encoded representation of the property's actual value (e.g., `"DNS-IP"`). + +By standardizing on this minimal structure, `SimpleProperty` allows assets and relations in the model to be richly annotated without enforcing strict typing or domain-specific schemas up front. This supports extensibility, integration with heterogeneous data sources, and future evolution of the model. + +In practice, `SimpleProperty` entries are often used when importing information from external tools, integrating OSINT data, or performing enrichment tasks across discovered assets and relations. The model treats them as first-class citizens in the graph, enabling reasoning, filtering, and correlation based on any attached properties. + +## :fontawesome-solid-tags: SimpleProperty Attributes + +| Attributes | Type | Required | Description | +| :--------: | :----: | :--------: | :----------- | +| `property_name` | string | :material-check-decagram: | A string that identifies the nature or role of the property | +| `property_value` | string | :material-check-decagram: | A string-encoded representation of the property's actual value | diff --git a/docs/open_asset_model/properties/vuln_property.md b/docs/open_asset_model/properties/vuln_property.md new file mode 100644 index 0000000..ae8f54d --- /dev/null +++ b/docs/open_asset_model/properties/vuln_property.md @@ -0,0 +1,27 @@ +# :simple-owasp: VulnProperty + +The `VulnProperty` is a specialized property type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) used to represent basic vulnerability information associated with an asset or relation. It is designed to capture structured yet concise details about known or observed security issues, such as CVEs, misconfigurations, or weak service configurations. + +Each `VulnProperty` instance describes a single vulnerability and is linked to the asset or relationship it affects. This allows for clear attribution of risk within the asset graph and enables reasoning about exposure across a discovered attack surface. + +The `VulnProperty` structure includes: + +- **ID** – A unique identifier for the vulnerability entry, often matching a standard enumeration such as a CVE ID (e.g., `CVE-2024-12345`). +- **Description** – A brief summary of the vulnerability's nature or impact. +- **Source** – The origin of the vulnerability data, such as the scanner or source system that identified it (e.g., `nuclei`, `cvefeed`, `custom-rule-engine`). +- **Category** – A high-level classification of the vulnerability, such as `exposed-service`, `software-vuln`, or `configuration`. +- **Enumeration** – A standardized vulnerability taxonomy used to identify the issue, such as `CVE`, `CWE`, or a custom identifier. +- **Reference** – A URL or external reference to more detailed information (e.g., an NVD page or vendor advisory). + +By standardizing how vulnerability metadata is attached to assets and relations, `VulnProperty` supports efficient integration of findings from vulnerability scanners, intelligence feeds, and custom assessment tooling. It also facilitates filtering, correlation, and prioritization of risks during triage or remediation workflows. + +## :fontawesome-solid-tags: VulnProperty Attributes + +| Attributes | Type | Required | Description | +| :----------------: | :--------: | :----------: | :------------- | +| `id` | string | :material-check-decagram: | A unique identifier for the vulnerability (e.g., `CVE-2024-12345`) | +| `desc` | string | :material-check-decagram: | A brief human-readable summary of the vulnerability | +| `source` | string | :material-checkbox-blank-circle-outline: | The name of the tool, feed, or method that reported the vulnerability | +| `category` | string | :material-checkbox-blank-circle-outline: | A general classification of the vulnerability (e.g., `software-vuln`) | +| `enum` | string | :material-checkbox-blank-circle-outline: | The taxonomy or enumeration system used (e.g., `CVE`, `CWE`) | +| `ref` | string | :material-checkbox-blank-circle-outline: | An optional reference URL for more information about the vulnerability | From 02b36ccc4686c08d0604c06548a22d59b1aacd96 Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 30 Jun 2025 16:51:48 -0400 Subject: [PATCH 14/45] updates --- docs/open_asset_model/assets/fqdn.md | 2 +- .../properties/source_property.md | 185 ++---------------- .../relations/simple_relation.md | 5 +- .../relations/srv_dns_relation.md | 3 +- mkdocs.yml | 23 ++- 5 files changed, 33 insertions(+), 185 deletions(-) diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 0bdb133..63aeee9 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -5,7 +5,7 @@ The *Fully Qualified Domain Name* (**FQDN**) asset represents a complete and una ## :material-dns: FQDN Attributes | Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| :--------: | :----: | :--------: | :----------- | | `name` | string | :material-check-decagram: | Unique fully qualified domain name (e.g. www.example.com) | ## :material-dns: FQDN Properties diff --git a/docs/open_asset_model/properties/source_property.md b/docs/open_asset_model/properties/source_property.md index 4c2898a..536b291 100644 --- a/docs/open_asset_model/properties/source_property.md +++ b/docs/open_asset_model/properties/source_property.md @@ -1,180 +1,21 @@ -# :simple-owasp: `Property` +# :simple-owasp: SourceProperty -The [`property.go`](https://github.com/owasp-amass/open-asset-model/blob/master/property.go) file defines the **core functionality** for managing and representing asset properties within the **Open Asset Model**. It provides a standardized way to **store, categorize, and serialize metadata** associated with various asset types. +The `SourceProperty` is a specialized property type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) that captures context about where that information came from. This makes `SourceProperty` especially valuable in scenarios where provenance, traceability, and confidence are essential. -## Table of Contents +The `SourceProperty` allows consumers of the model to understand *how* and *from where* a piece of data was obtained. This is particularly useful when integrating data from OSINT sources, third-party APIs, security tools, or historical archives. -- [Overview](#overview) -- [Property Interface](#property-interface) -- [PropertyType Enumeration](#propertytype-enumeration) -- [PropertyList Variable](#propertylist-variable) -- [Usage](#usage) +Each `SourceProperty` includes the following components: ---- +- **Name** – Name of the engine plugin that discovered the asset or relation (e.g., `DNS-IP`, `RDAP`, `GLIEF`). +- **Confidence** – A numerical value providing a percentage of confidence (e.g., `50`, `75`, `100`). -## **//** Overview +By coupling assets and relations with their origin, `SourceProperty` supports trust-aware decision-making and enables the model to be used in environments where data reliability and reproducibility are critical. Consumers can prioritize or filter information based on its source, aiding in validation and reducing false positives in automated analysis pipelines. -The **Open Asset Model** provides a structured approach to handling **metadata** for different asset types. The **`property.go`** file establishes key components that ensure **consistency and extensibility** in property management: +All Amass engine plugins mark discovered assets and associations between them with source information to build the breadcrumb trail and better understand how the discoveries were made during the enumeration process. -- **Property Interface** – Defines a common structure that all asset properties must implement. +## :fontawesome-solid-tags: SourceProperty Attributes -- **PropertyType Enumeration** – Predefined constants that categorize different asset properties. - -- **PropertyList** – A list of all supported property types for **validation and iteration**. - -These components allow **standardized metadata representation**, ensuring structured **asset intelligence, security analysis, and interoperability** across various applications. - ---- - -## **//** Property Interface - -The **Property interface** defines the required methods that any asset property must implement. This ensures that all properties are represented in a consistent format. - -```go -// Property Interface -type Property interface { - Name() string // Returns the property name (identifier) - Value() string // Returns the value of the property - PropertyType() PropertyType // Categorizes the property type - JSON() ([]byte, error) // Serializes the property to JSON -} -``` - -| **Method** | **Return Type** | **Description** | -| --------------- -----| ---------------------- | ------------------------------------------------------| -| **`Name()`** | `string` | Returns the **identifier name** of the property | -| **`Value()`** | `string` | Retrieves the value associated with the property | -| **`PropertyType()`** | `PropertyType` | Provides the **category** of the property | -| **`JSON()`** | `([]byte, error)` | Serializes the **property into JSON format** | - -### Usage Considerations - -- **Encapsulation**: Ensures that property data remains structured. - -- **Serialization**: Allows for seamless integration with JSON-based systems. - -- **Extensibility**: Developers can introduce new property types while maintaining compatibility. - ---- - -## **//** PropertyType Enumeration - -The `PropertyType` is a **string alias** that categorizes asset properties, ensuring clarity and **structured property handling**. - -```go -type PropertyType string -``` - - -**Predefined Property Types:** - -| **Constant Name** | **Actual Value** | **Description** | -| ------------------------- | -----------------------| --------------------------------------------------------| -| **`DNSRecordProperty`** | `"DNSRecordProperty"` | Represents properties related to **DNS records** | -| **`SimpleProperty`** | `"SimpleProperty"` | **General-purpose** property for miscellaneous metadata | -| **`SourceProperty`** | `"SourceProperty"` | Indicates the **origin or source** of asset data | -| **`VulnProperty`** | `"VulnProperty"` | Represents **vulnerability-related** properties | - - -**Property Type Declaration** - -```go -const ( - DNSRecordProperty PropertyType = "DNSRecordProperty" - SimpleProperty PropertyType = "SimpleProperty" - SourceProperty PropertyType = "SourceProperty" - VulnProperty PropertyType = "VulnProperty" -) -``` - ---- - -## **//** PropertyList Variable - -To facilitate **validation and iteration**, the model defines **`PropertyList`**, which contains all property types. - -```go -var PropertyList = []PropertyType{ - DNSRecordProperty, SimpleProperty, SourceProperty, VulnProperty, -} -``` - -**Why `PropertyList` is Useful:** - -- **Validation**: Ensures that only **supported property types** are used. - -- **Iteration**: Allows for **dynamic property processing** across multiple systems. - -- **Maintainability**: New property types can be **added easily** while keeping the model consistent. - ---- - -## **//** Usage - -The **Open Asset Model** uses **`property.go`** for structured metadata handling. - -Below is an example demonstrating how to: - -- **Retrieve property type information**. - -- **Serialize properties to JSON**. - -- **Validate whether a property type exists in `PropertyList`**. - -```go -package main - -import ( - "encoding/json" - "fmt" - "github.com/owasp-amass/open-asset-model" -) - -func main() { - // Define an example property type (predefined in the model) - propertyType := open_asset_model.DNSRecordProperty - - // Serialize the property type into JSON format - jsonData, err := json.Marshal(propertyType) - if err != nil { - fmt.Println("Error serializing property type to JSON:", err) - return - } - - fmt.Printf("Property Type: %s\n", propertyType) - fmt.Printf("Serialized JSON: %s\n", string(jsonData)) - - // Validate if the property type exists in PropertyList - isValid := false - for _, p := range open_asset_model.PropertyList { - if p == propertyType { - isValid = true - break - } - } - - if isValid { - fmt.Println("The property type is valid! ✅") - } else { - fmt.Println("The property type is invalid! ❌") - } -} -``` - ---- - -## **//** Summary - -The **`property.go`** file is a fundamental part of the **Open Asset Model**, ensuring **structured metadata representation** for asset intelligence workflows. - -Key takeaways: - -- **Defines a structured Property interface** to standardize asset metadata. - -- **Enumerates property types** to ensure data consistency. - -- **Provides JSON serialization support** for data interchange. - -- **Includes `PropertyList`** to facilitate property type validation and iteration. - -By following this structured approach, **contributors** can extend the property model, while **users** can leverage predefined properties for efficient asset intelligence and metadata management. \ No newline at end of file +| Attributes | Type | Required | Description | +| :--------: | :----: | :--------: | :----------- | +| `name` | string | :material-check-decagram: | Name of the engine plugin that discovered the asset or relation | +| `confidence` | number | :material-checkbox-blank-circle-outline: | A value 0 through 100 representing the confidence percentage | diff --git a/docs/open_asset_model/relations/simple_relation.md b/docs/open_asset_model/relations/simple_relation.md index 7a22b74..a0545ae 100644 --- a/docs/open_asset_model/relations/simple_relation.md +++ b/docs/open_asset_model/relations/simple_relation.md @@ -1,6 +1,6 @@ # :simple-owasp: SimpleRelation -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. +The **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. - **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). @@ -13,12 +13,11 @@ In essence, the `SimpleRelation` is a clean, minimal tool used within the OAM to ## :material-relation-one-to-one: SimpleRelation Attributes | Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| :--------: | :----: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | ## :material-relation-one-to-one: SimpleRelation Properties | Property Type | Property Name | Description | | :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SimpleRelation | diff --git a/docs/open_asset_model/relations/srv_dns_relation.md b/docs/open_asset_model/relations/srv_dns_relation.md index 8eeee44..736aaa8 100644 --- a/docs/open_asset_model/relations/srv_dns_relation.md +++ b/docs/open_asset_model/relations/srv_dns_relation.md @@ -18,7 +18,7 @@ In summary, `SRVDNSRelation` brings full support for SRV record semantics into t ## :material-relation-one-to-one: SRVDNSRelation Attributes | Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| :--------: | :----: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | | `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | | `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | @@ -31,5 +31,4 @@ In summary, `SRVDNSRelation` brings full support for SRV record semantics into t | Property Type | Property Name | Description | | :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SRVDNSRelation | diff --git a/mkdocs.yml b/mkdocs.yml index b44e0f0..76d658b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -134,13 +134,22 @@ nav: - URL: open_asset_model/assets/url.md - Relations: - Relations: open_asset_model/relations/index.md - - Simple Relation: open_asset_model/relations/simple_relation.md + - BasicDNSRelation: open_asset_model/relations/basic_dns_relation.md + - PortRelation: open_asset_model/relations/port_relation.md + - PrefDNSRelation: open_asset_model/relations/pref_dns_relation.md + - SimpleRelation: open_asset_model/relations/simple_relation.md + - SRVDNSRelation: open_asset_model/relations/srv_dns_relation.md - Properties: - Properties: open_asset_model/properties/index.md - - Source Property: open_asset_model/properties/source_property.md - - Configuration: configuration/configuration.md - - Data Sources: data_sources/data_sources.md - - AssetDB: assetDB/assetDB.md - - Dashboards: dashboards/dashboards.md - - Change Log: changelog/changelog.md + - DNSRecordProperty: open_asset_model/properties/dns_property.md + - SimpleProperty: open_asset_model/properties/simple_property.md + - SourceProperty: open_asset_model/properties/source_property.md + - VulnProperty: open_asset_model/properties/vuln_property.md + - Configuration: + - Configuration: open_asset_model/configuration/index.md + - Data Sources: open_asset_model/configuration/data_sources.md + - Asset DB: + - Asset DB: asset_db/index.md + - Triples: asset_db/triples.md + - Transformations: asset_db/transformations.md - Contributing: contributing/contributing.md From 7211a382b2e8a8e6a3b9e9889f88eda7c60388f9 Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 00:24:22 -0400 Subject: [PATCH 15/45] initial commit --- .../assets/autonomous_system.md | 1 + docs/open_asset_model/assets/netblock.md | 48 +++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/open_asset_model/assets/autonomous_system.md create mode 100644 docs/open_asset_model/assets/netblock.md diff --git a/docs/open_asset_model/assets/autonomous_system.md b/docs/open_asset_model/assets/autonomous_system.md new file mode 100644 index 0000000..2c23a0e --- /dev/null +++ b/docs/open_asset_model/assets/autonomous_system.md @@ -0,0 +1 @@ +# :simple-owasp: AutonomousSystem diff --git a/docs/open_asset_model/assets/netblock.md b/docs/open_asset_model/assets/netblock.md new file mode 100644 index 0000000..a76bd28 --- /dev/null +++ b/docs/open_asset_model/assets/netblock.md @@ -0,0 +1,48 @@ +# :simple-owasp: Netblock + +The **Netblock** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a contiguous range of IP addresses, typically expressed in CIDR notation and often associated with an Autonomous System (AS). + +- **Definition:** A `Netblock` defines an IP range (e.g., `203.0.113.0/24` or `2001:db8::/32`) that encompasses many individual IP addresses. It usually reflects address space allocated to or announced by an Autonomous System and may represent organizational, geographic, or functional network boundaries. + +- **Purpose:** This asset type enables modeling of large-scale network ownership and infrastructure grouping. By identifying which IP addresses fall within a specific `Netblock`, analysts can track organizational control, ISP allocation, or exposure zones across the internet or private networks. It's especially useful in asset discovery, threat attribution, and risk scoping. + +- **Design Choice:** The `Netblock` provides an abstract, high-level view of address space without enumerating every IP address it contains. It can be related to specific `IPAddress` or `AutonomousSystem` assets through appropriate relations, enabling hierarchical and scalable modeling of internet-facing infrastructure. + +In summary, the `Netblock` asset type captures ranges of IP addresses in a compact, structured way, supporting infrastructure mapping, ownership tracking, and contextual analysis of network exposure in the OAM. + +## :fontawesome-solid-network-wired: Netblock Attributes + +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | +| `cidr` | string | :material-check-decagram: | Contains the IP address range (e.g., `203.0.113.0/24`) | +| `type` | string | :material-check-decagram: | The IP protocol version, typically either `IPv4` or `IPv6` | + +## :fontawesome-solid-network-wired: Netblock Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Netblock | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Netblock | + +## :fontawesome-solid-network-wired: Netblock Outgoing Relations + +```mermaid +graph TD +netblock["Netblock"] +ipaddr["IPAddress"] +contains@{ shape: braces, label: "contains" } +netblock --o contains +contains --> ipaddr + +iprec["IPNetRecord"] +regrel@{ shape: braces, label: "registration"} +netblock --o regrel +regrel --> iprec +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `contains` | [`IPAddress`](./ip_address.md) | Links a Netblock to an IPAddress within the CIDR range | +| [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`IPNetRecord`](./ipnet_record.md) | Links a network to its associated registration data | From a4ffe9026003b2ca38ba031901a39232a5f1b34a Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 00:24:49 -0400 Subject: [PATCH 16/45] updates --- .../open_asset_model/assets/contact_record.md | 12 ++--- docs/open_asset_model/assets/fqdn.md | 26 ++++++---- docs/open_asset_model/assets/ip_address.md | 50 +++++++++++++++++++ docs/open_asset_model/assets/organization.md | 2 +- docs/open_asset_model/assets/url.md | 1 + .../properties/dns_property.md | 4 +- .../properties/simple_property.md | 4 +- .../properties/source_property.md | 4 +- .../properties/vuln_property.md | 4 +- .../relations/basic_dns_relation.md | 9 ++-- .../relations/port_relation.md | 9 ++-- .../relations/pref_dns_relation.md | 9 ++-- .../relations/simple_relation.md | 8 +-- .../relations/srv_dns_relation.md | 8 +-- mkdocs.yml | 1 + 15 files changed, 104 insertions(+), 47 deletions(-) diff --git a/docs/open_asset_model/assets/contact_record.md b/docs/open_asset_model/assets/contact_record.md index 70fcdfe..cf56f6c 100644 --- a/docs/open_asset_model/assets/contact_record.md +++ b/docs/open_asset_model/assets/contact_record.md @@ -4,14 +4,14 @@ The **ContactRecord** asset serves as a connective entity that maintains a relia ## :material-contacts: ContactRecord Attributes -| Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `discovered_at` | string | :material-check-decagram: | Unique URL or path to the contact information | ## :material-contacts: ContactRecord Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this ContactRecord | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this ContactRecord | @@ -54,8 +54,8 @@ simple6 --> url --- -| Relation Type | Relation Label | Target Assets | Description | -| :--------------: | :---------------: | :--------------: | :------------ | +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | | [`SimpleRelation`](../relations/simple_relation.md) | `fqdn` | [`FQDN`](#fqdn) | Represents a FQDN discovered in the contact information | | [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](#identifer) | Represents an ID (e.g. email address) in the contact information | | [`SimpleRelation`](../relations/simple_relation.md) | `organization` | [`Organization`](#organization) | Represents an organization name in the contact information | diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 63aeee9..47df8e3 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -1,17 +1,25 @@ # :simple-owasp: FQDN -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 the organization digital footprint. +The **FQDN** (Fully Qualified Domain Name) asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a fully specified domain name that uniquely identifies a resource within the DNS hierarchy. FQDNs are foundational elements in *open-source intelligence (OSINT)* and are essential to building a thorough *attack surface intelligence* profile. + +- **Definition:** An `FQDN` asset contains a domain name string (e.g., `www.example.com`). It refers to the complete and unambiguous name of a host or service as resolved through DNS. + +- **Purpose:** This asset type enables the modeling of DNS-resolvable names as distinct entities within an attack surface. `FQDN` assets are critical for tracing how external users and systems access internal infrastructure, through domain-based references rather than direct IP addresses. + +- **Design Choice:** By treating FQDNs as first-class assets, the model supports DNS resolution chains (via relations like `BasicDNSRelation`, `PrefDNSRelation`, and `SRVDNSRelation`) and links to IP addresses, services, or other host-based assets. This allows security teams to analyze exposure, misconfigurations, or shadow assets rooted in DNS name usage. + +In summary, the `FQDN` asset type provides a precise and structured way to represent domain-based identifiers in the OAM, serving as a core building block for understanding how infrastructure is referenced and accessed over the internet or internal networks. ## :material-dns: FQDN Attributes -| Attributes | Type | Required | Description | -| :--------: | :----: | :--------: | :----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `name` | string | :material-check-decagram: | Unique fully qualified domain name (e.g. www.example.com) | ## :material-dns: FQDN Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this FQDN | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this FQDN | | [`DNSRecordProperty`](../properties/dns_property.md) | `dns_record` | Represents a DNS record for this FQDN that provides only data | @@ -26,7 +34,7 @@ nodeRel@{ shape: braces, label: "node"} fqdn1 --o nodeRel nodeRel --> fqdn2 -ipaddr["IP Address"] +ipaddr["IPAddress"] basicdns1@{ shape: braces, label: "dns_record"} basicdns2@{ shape: braces, label: "dns_record"} fqdn1 --o basicdns1 @@ -49,7 +57,7 @@ port@{ shape: braces, label: "port"} fqdn2 --o port port --> service -domrec["Domain Record"] +domrec["DomainRecord"] regrel@{ shape: braces, label: "registration"} fqdn1 --o regrel regrel --> domrec @@ -57,8 +65,8 @@ regrel --> domrec --- -| Relation Type | Relation Label | Target Assets | Description | -| :--------------: | :---------------: | :--------------: | :------------ | +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | | [`BasicDNSRelation`](../relations/basic_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Represents most RR types | | [`PrefDNSRelation`](../relations/pref_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn) | Utilized for RR types that have a preference attribute | | [`SRVDNSRelation`](../relations/srv_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn) | Represents the SRV Resource Record type | diff --git a/docs/open_asset_model/assets/ip_address.md b/docs/open_asset_model/assets/ip_address.md index e69de29..cbb248e 100644 --- a/docs/open_asset_model/assets/ip_address.md +++ b/docs/open_asset_model/assets/ip_address.md @@ -0,0 +1,50 @@ +# :simple-owasp: IPAddress + +The **IPAddress** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a concrete IP address and its associated protocol version, used to uniquely identify network endpoints in the model. + +- **Definition:** An `IPAddress` asset holds two primary attributes: + - `address`: The actual IP address in string format (e.g., `192.0.2.1` or `2001:db8::1`). + - `type`: The IP protocol version, typically either `IPv4` or `IPv6`. + +- **Purpose:** This asset type enables the explicit representation of individual IP addresses as first-class entities within the attack surface model. These can be linked to other assets (e.g., domains, ports, hosts) to show how infrastructure components are exposed or interconnected via the network. + +- **Design Choice:** By separating the address from its protocol type, the model supports clear differentiation between IPv4 and IPv6, even when similar address representations exist. This structure also improves compatibility with analysis tools and threat modeling processes that treat IPv4 and IPv6 differently due to their behavior and reachability characteristics. + +In summary, the `IPAddress` asset provides a simple yet precise way to model network identity, supporting both IPv4 and IPv6, and serving as a foundational building block for visualizing and analyzing network-layer exposure in the OAM. + +## :material-ip-outline: IPAddress Attributes + +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | +| `address` | string | :material-check-decagram: | Unique Internet Protocol address (e.g. 72.237.4.113) | +| `type` | string | :material-check-decagram: | The IP protocol version, typically either `IPv4` or `IPv6` | + +## :material-ip-outline: IPAddress Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this IPAddress | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this IPAddress | + +## :material-ip-outline: IPAddress Outgoing Relations + +```mermaid +graph TD +ipaddr["IPAddress"] +fqdn["FQDN (e.g. 113.4.237.72.in-addr.arpa)"] +ptr@{ shape: braces, label: "ptr_record"} +ipaddr --o ptr +ptr --> fqdn + +service["Service"] +port@{ shape: braces, label: "port"} +ipaddr --o port +port --> service +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `ptr_record` | [`FQDN`](#fqdn) | Links an IPAddress to its DNS name used in PTR records | +| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](#service) | Represents a port at the IPAddress with a responding service | diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 8b13789..48f82ba 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -1 +1 @@ - +# :simple-owasp: Organization diff --git a/docs/open_asset_model/assets/url.md b/docs/open_asset_model/assets/url.md index e69de29..56751f6 100644 --- a/docs/open_asset_model/assets/url.md +++ b/docs/open_asset_model/assets/url.md @@ -0,0 +1 @@ +# :simple-owasp: URL diff --git a/docs/open_asset_model/properties/dns_property.md b/docs/open_asset_model/properties/dns_property.md index 8cb8500..0262e81 100644 --- a/docs/open_asset_model/properties/dns_property.md +++ b/docs/open_asset_model/properties/dns_property.md @@ -15,8 +15,8 @@ By modeling DNS data with a dedicated property type, `DNSRecordProperty` enables ## :fontawesome-solid-tags: DNSRecordProperty Attributes -| Attributes | Type | Required | Description | -| :------------------: | :--------: | :----------: | :------------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `property_name` | string | :material-check-decagram: | The name of the property that should be `dns_record` | | `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | | `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | diff --git a/docs/open_asset_model/properties/simple_property.md b/docs/open_asset_model/properties/simple_property.md index 0d19b37..ebd6de6 100644 --- a/docs/open_asset_model/properties/simple_property.md +++ b/docs/open_asset_model/properties/simple_property.md @@ -15,7 +15,7 @@ In practice, `SimpleProperty` entries are often used when importing information ## :fontawesome-solid-tags: SimpleProperty Attributes -| Attributes | Type | Required | Description | -| :--------: | :----: | :--------: | :----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `property_name` | string | :material-check-decagram: | A string that identifies the nature or role of the property | | `property_value` | string | :material-check-decagram: | A string-encoded representation of the property's actual value | diff --git a/docs/open_asset_model/properties/source_property.md b/docs/open_asset_model/properties/source_property.md index 536b291..5da1412 100644 --- a/docs/open_asset_model/properties/source_property.md +++ b/docs/open_asset_model/properties/source_property.md @@ -15,7 +15,7 @@ All Amass engine plugins mark discovered assets and associations between them wi ## :fontawesome-solid-tags: SourceProperty Attributes -| Attributes | Type | Required | Description | -| :--------: | :----: | :--------: | :----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `name` | string | :material-check-decagram: | Name of the engine plugin that discovered the asset or relation | | `confidence` | number | :material-checkbox-blank-circle-outline: | A value 0 through 100 representing the confidence percentage | diff --git a/docs/open_asset_model/properties/vuln_property.md b/docs/open_asset_model/properties/vuln_property.md index ae8f54d..2eeffed 100644 --- a/docs/open_asset_model/properties/vuln_property.md +++ b/docs/open_asset_model/properties/vuln_property.md @@ -17,8 +17,8 @@ By standardizing how vulnerability metadata is attached to assets and relations, ## :fontawesome-solid-tags: VulnProperty Attributes -| Attributes | Type | Required | Description | -| :----------------: | :--------: | :----------: | :------------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `id` | string | :material-check-decagram: | A unique identifier for the vulnerability (e.g., `CVE-2024-12345`) | | `desc` | string | :material-check-decagram: | A brief human-readable summary of the vulnerability | | `source` | string | :material-checkbox-blank-circle-outline: | The name of the tool, feed, or method that reported the vulnerability | diff --git a/docs/open_asset_model/relations/basic_dns_relation.md b/docs/open_asset_model/relations/basic_dns_relation.md index 73c6cfd..aa5dd62 100644 --- a/docs/open_asset_model/relations/basic_dns_relation.md +++ b/docs/open_asset_model/relations/basic_dns_relation.md @@ -12,8 +12,8 @@ In summary, `BasicDNSRelation` enables efficient modeling of essential DNS relat ## :material-relation-one-to-one: BasicDNSRelation Attributes -| Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | | `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | | `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | @@ -21,7 +21,6 @@ In summary, `BasicDNSRelation` enables efficient modeling of essential DNS relat ## :material-relation-one-to-one: BasicDNSRelation Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this BasicDNSRelation | diff --git a/docs/open_asset_model/relations/port_relation.md b/docs/open_asset_model/relations/port_relation.md index 5582e08..2568729 100644 --- a/docs/open_asset_model/relations/port_relation.md +++ b/docs/open_asset_model/relations/port_relation.md @@ -12,15 +12,14 @@ In essence, `PortRelation` adds precise network exposure context to the OAM, let ## :material-relation-one-to-one: PortRelation Attributes -| Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | | `port_number` | number | :material-check-decagram: | The number assigned to the discovered port | | `protocol` | string | :material-check-decagram: | The protocol stack of the specified port | ## :material-relation-one-to-one: PortRelation Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this PortRelation | diff --git a/docs/open_asset_model/relations/pref_dns_relation.md b/docs/open_asset_model/relations/pref_dns_relation.md index f0ca5d1..13097df 100644 --- a/docs/open_asset_model/relations/pref_dns_relation.md +++ b/docs/open_asset_model/relations/pref_dns_relation.md @@ -12,8 +12,8 @@ In summary, `PrefDNSRelation` extends basic DNS modeling by introducing priority ## :material-relation-one-to-one: PrefDNSRelation Attributes -| Attributes | Type | Required | Description | -| -------- | ---- | :--------: | ----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | | `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | | `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | @@ -22,7 +22,6 @@ In summary, `PrefDNSRelation` extends basic DNS modeling by introducing priority ## :material-relation-one-to-one: PrefDNSRelation Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | -| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this relationship | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this PrefDNSRelation | diff --git a/docs/open_asset_model/relations/simple_relation.md b/docs/open_asset_model/relations/simple_relation.md index a0545ae..1455816 100644 --- a/docs/open_asset_model/relations/simple_relation.md +++ b/docs/open_asset_model/relations/simple_relation.md @@ -12,12 +12,12 @@ In essence, the `SimpleRelation` is a clean, minimal tool used within the OAM to ## :material-relation-one-to-one: SimpleRelation Attributes -| Attributes | Type | Required | Description | -| :--------: | :----: | :--------: | :----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | ## :material-relation-one-to-one: SimpleRelation Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SimpleRelation | diff --git a/docs/open_asset_model/relations/srv_dns_relation.md b/docs/open_asset_model/relations/srv_dns_relation.md index 736aaa8..3bff5eb 100644 --- a/docs/open_asset_model/relations/srv_dns_relation.md +++ b/docs/open_asset_model/relations/srv_dns_relation.md @@ -17,8 +17,8 @@ In summary, `SRVDNSRelation` brings full support for SRV record semantics into t ## :material-relation-one-to-one: SRVDNSRelation Attributes -| Attributes | Type | Required | Description | -| :--------: | :----: | :--------: | :----------- | +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | | `label` | string | :material-check-decagram: | The label for the relation between two assets | | `header.rr_type` | number | :material-check-decagram: | Specifies the type of resource within the DNS record | | `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | @@ -29,6 +29,6 @@ In summary, `SRVDNSRelation` brings full support for SRV record semantics into t ## :material-relation-one-to-one: SRVDNSRelation Properties -| Property Type | Property Name | Description | -| :--------------: | :---------------: | :------------ | +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SRVDNSRelation | diff --git a/mkdocs.yml b/mkdocs.yml index 76d658b..a52ad82 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,6 +127,7 @@ nav: - FundsTransfer: open_asset_model/assets/funds_transfer.md - Identifier: open_asset_model/assets/identifier.md - IPAddress: open_asset_model/assets/ip_address.md + - Netblock: open_asset_model/assets/netblock.md - Organization: open_asset_model/assets/organization.md - Person: open_asset_model/assets/person.md - Product: open_asset_model/assets/product.md From 5e57038bfac1a1c901eff8f3c8835d0769d953cb Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 13:09:52 -0400 Subject: [PATCH 17/45] fixes --- docs/open_asset_model/assets/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/open_asset_model/assets/index.md b/docs/open_asset_model/assets/index.md index 307bf09..0d0b469 100644 --- a/docs/open_asset_model/assets/index.md +++ b/docs/open_asset_model/assets/index.md @@ -16,11 +16,11 @@ In the **Open Asset Model (OAM)**, *assets* are the atomic units of knowledge th An asset is **not** just a label; it is a self‑contained document that answers three questions: -1. **What is it?**\ +1. **What is it?** A type‑specific schema (e.g., *FQDN*, *TLSCertificate*, *AutonomousSystem*). -2. **Where did it come from?**\ +2. **Where did it come from?** One or more *DiscoveryMethods* with timestamps and collection method. -3. **How certain are we?**\ +3. **How certain are we?** A *confidence* score that downstream pipelines can use to gate actions. ## :material-graph-outline: Asset Taxonomy (Partial) From 5648366243794a034e9a70f7a098c095cfb2d6b2 Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 20:27:34 -0400 Subject: [PATCH 18/45] updates --- .../assets/autonomous_system.md | 46 ++++++++ docs/open_asset_model/assets/fqdn.md | 12 +- docs/open_asset_model/assets/ip_address.md | 4 +- docs/open_asset_model/assets/organization.md | 108 ++++++++++++++++++ .../assets/tls_certificate.md | 102 +++++++++++++++++ docs/open_asset_model/assets/url.md | 76 ++++++++++++ mkdocs.yml | 1 + 7 files changed, 341 insertions(+), 8 deletions(-) diff --git a/docs/open_asset_model/assets/autonomous_system.md b/docs/open_asset_model/assets/autonomous_system.md index 2c23a0e..853e92d 100644 --- a/docs/open_asset_model/assets/autonomous_system.md +++ b/docs/open_asset_model/assets/autonomous_system.md @@ -1 +1,47 @@ # :simple-owasp: AutonomousSystem + +The `AutonomousSystem` is an asset type defined in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) that represents a unique network entity on the global Internet, identified by an Autonomous System Number (ASN). These systems are managed by organizations—such as ISPs, cloud providers, enterprises, and academic institutions—that control a block of IP address space and operate a distinct routing policy. + +Autonomous Systems are foundational elements of the Internet’s infrastructure. In the context of external attack surface management (EASM), they serve as a key attribution point between an organization and the IP address ranges it announces and operates. By modeling these as first-class assets, the OAM enables analysts and automation to reason about ownership, geography, provider relationships, and changes in network footprint. + +Each `AutonomousSystem` asset includes: + +- **ASN** – The unique numeric identifier assigned by a regional internet registry (RIR), such as `15169`. + +The `AutonomousSystem` asset is often used as a root for discovering related IP ranges (`NetBlock` assets), establishing legal entity associations, or monitoring changes in Internet-facing infrastructure. It is also useful in tracking adversary infrastructure, attributing threat activity, and resolving the ownership of obscure or third-party hosted assets. + +## :material-router-network: AutonomousSystem Attributes + +| Attributes | Type | Required | Description | +| :--------------: | :-------: | :--------: | :----------- | +| `number` | number | :material-check-decagram: | The unique Autonomous System Number assigned to the network | + +## :material-router-network: AutonomousSystem Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this AutonomousSystem | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this AutonomousSystem | + +## :material-router-network: AutonomousSystem Outgoing Relations + +```mermaid +graph TD +asn["AutonomousSystem"] +netblock["Netblock (e.g. 72.237.4.0/24)"] +announces@{ shape: braces, label: "announces"} +asn --o announces +announces --> netblock + +autnum["AutnumRecord"] +regrel@{ shape: braces, label: "registration"} +asn --o regrel +regrel --> autnum +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `announces` | [`Netblock`](./netblock.md) | Links an IPAddress to its DNS name used in PTR records | +| [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`AutnumRecord`](./autnum_record.md) | Links a ASN to its associated registration data | diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 47df8e3..8388566 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -67,9 +67,9 @@ regrel --> domrec | Relation Type | Relation Label | Target Assets | Description | | :-----------------: | :----------------: | :--------------: | :------------ | -| [`BasicDNSRelation`](../relations/basic_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn), [`IPAddress`](#ip_address) | Represents most RR types | -| [`PrefDNSRelation`](../relations/pref_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn) | Utilized for RR types that have a preference attribute | -| [`SRVDNSRelation`](../relations/srv_dns_relation.md) | `dns_record` | [`FQDN`](#fqdn) | Represents the SRV Resource Record type | -| [`SimpleRelation`](../relations/simple_relation.md) | `node` | [`FQDN`](#fqdn) | Links a DNS zone apex to nodes within the zone | -| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](#service) | Represents a port at the FQDN with a responding service | -| [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`DomainRecord`](#domain_record) | Links a root domain to its associated registration data | +| [`BasicDNSRelation`](../relations/basic_dns_relation.md) | `dns_record` | `FQDN`, [`IPAddress`](./ip_address.md) | Represents most RR types | +| [`PrefDNSRelation`](../relations/pref_dns_relation.md) | `dns_record` | `FQDN` | Utilized for RR types that have a preference attribute | +| [`SRVDNSRelation`](../relations/srv_dns_relation.md) | `dns_record` | `FQDN` | Represents the SRV Resource Record type | +| [`SimpleRelation`](../relations/simple_relation.md) | `node` | `FQDN` | Links a DNS zone apex to nodes within the zone | +| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents a port at the FQDN with a responding service | +| [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`DomainRecord`](./domain_record.md) | Links a root domain to its associated registration data | diff --git a/docs/open_asset_model/assets/ip_address.md b/docs/open_asset_model/assets/ip_address.md index cbb248e..072dce5 100644 --- a/docs/open_asset_model/assets/ip_address.md +++ b/docs/open_asset_model/assets/ip_address.md @@ -46,5 +46,5 @@ port --> service | Relation Type | Relation Label | Target Assets | Description | | :-----------------: | :----------------: | :--------------: | :------------ | -| [`SimpleRelation`](../relations/simple_relation.md) | `ptr_record` | [`FQDN`](#fqdn) | Links an IPAddress to its DNS name used in PTR records | -| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](#service) | Represents a port at the IPAddress with a responding service | +| [`SimpleRelation`](../relations/simple_relation.md) | `ptr_record` | [`FQDN`](./fqdn.md) | Links an IPAddress to its DNS name used in PTR records | +| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents a port at the IPAddress with a responding service | diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 48f82ba..90ba9eb 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -1 +1,109 @@ # :simple-owasp: Organization + +The `Organization` asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a real-world legal entity, such as a corporation, nonprofit, or government agency, that owns or operates digital infrastructure. This asset type is critical for enabling attribution, relationship mapping, and grouping of Internet-exposed resources under a common ownership structure. + +By representing organizations explicitly, the model supports a wide range of use cases including legal entity discovery, supply chain risk analysis, and asset attribution in large or decentralized environments. This asset often serves as the root from which other assets, such as IP ranges, domain names, and TLS certificates, are discovered and associated. + +Each `Organization` includes structured metadata such as: + +- **ID** – A globally unique identifier for the organization within the graph. +- **Name** – A commonly used name for the organization (e.g., `Acme Corp`). +- **Legal Name** – The formally registered legal name (e.g., `Acme Corporation, Inc.`). +- **Founding Date** – The year or date when the organization was established. +- **Jurisdiction** – The legal or regulatory jurisdiction where the entity is registered (e.g., `US-DE` for Delaware, United States). +- **Registration ID** – An optional formal identifier from a national registry (e.g., a company number or DUNS number). +- **Industry** – A general classification of the organization’s primary business activity (e.g., `Cloud Services`, `Financial Technology`). +- **Target Markets** – Geographic or sectoral regions the organization primarily serves. +- **Active** – A boolean indicating whether the organization is currently operational. +- **Nonprofit** – A boolean indicating whether the entity is a nonprofit organization. +- **Headcount** – An estimate of the number of employees. + +The `Organization` asset enables enrichment and correlation of digital infrastructure findings with publicly available business data. It plays a foundational role in external asset discovery workflows that begin from company metadata, such as legal names or registration information, and then pivot into technical assets like domains, netblocks, and services. + +## :octicons-organization-24: Organization Attributes + +| Attributes | Type | Required | Description | +|--------------------|-------------------|----------|-------------| +| `unique_id` | string | :material-check-decagram: | Unique identifier for the organization within the model | +| `name` | string | :material-check-decagram: | Common name used to identify the organization | +| `legal_name` | string | :material-check-circle: | Official registered name of the organization | +| `founding_date` | string (date) | :material-check-circle: | Date when the organization was founded (e.g., `2004-09-15`) | +| `jurisdiction` | string | :material-check-circle: | Legal jurisdiction of incorporation (e.g., `US-DE`) | +| `registration_id` | string | :material-check-circle: | Registered entity ID from a business registry | +| `industry` | string | :material-check-circle: | Sector classification (e.g., `Cybersecurity`, `E-Commerce`) | +| `target_markets` | array of strings | :material-check-circle: | Markets or regions the organization serves (e.g., `US`, `EU`) | +| `active` | boolean | :material-check-circle: | Whether the organization is currently active | +| `non_profit` | boolean | :material-check-circle: | Whether the organization is a nonprofit | +| `headcount` | number | :material-check-circle: | Approximate number of employees | + +## :octicons-organization-24: Organization Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Organization | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Organization | + + +## :octicons-organization-24: Organization Outgoing Relations + +```mermaid +graph TD +org["Organization"] +ident["Identifier"] +idrel@{ shape: braces, label: "id" } +org --o idrel +idrel --> ident + +loc["Location"] +locrel@{ shape: braces, label: "legal_address +hq_address +location" } +tls --o locrel +locrel --> loc + +org2["Organization"] +orgrel@{ shape: braces, label: "subsidiary +org_unit" } +org --o orgrel +orgrel --> org2 + +url["URL"] +urlrel@{ shape: braces, label: "website +social_media_profile" } +org --o urlrel +urlrel --> url + +account["Identifier"] +acctrel@{ shape: braces, label: "account" } +org --o acctrel +acctrel --> account + +person["Person"] +member@{ shape: braces, label: "member" } +org --o member +member --> person + +person2["Person"] +org3["Organization"] +funding@{ shape: braces, label: "funding_source" } +org --o funding +funding --> org3 +funding --> person2 +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the organization to alternative identifiers | +| [`SimpleRelation`](../relations/simple_relation.md) | `legal_address` | [`Location`](./location.md) | Links the organization to its legal street address | +| [`SimpleRelation`](../relations/simple_relation.md) | `hq_address` | [`Location`](./location.md) | Links the organization to the street address of its headquarters | +| [`SimpleRelation`](../relations/simple_relation.md) | `location` | [`Location`](./location.md) | Links the organization to the street address of an alternative location | +| [`SimpleRelation`](../relations/simple_relation.md) | `subsidiary` | `Organization` | Links the organization to one of its child organizations | +| [`SimpleRelation`](../relations/simple_relation.md) | `org_unit` | `Organization` | Links the organization to one of its sectors or departments that is externally visible | +| [`SimpleRelation`](../relations/simple_relation.md) | `account` | [`Account`](./account.md) | Links the organization to one of its digital or financial accounts | +| [`SimpleRelation`](../relations/simple_relation.md) | `member` | [`Person`](./person.md) | Links the organization to one of its employees identified as a `Person` asset | +| [`SimpleRelation`](../relations/simple_relation.md) | `san_ip_address` | [`IPAddress`](./ip_address.md) | Links the certificate to `IPAddress` assets found in the Subject Alternative Name (SAN) field | +| [`SimpleRelation`](../relations/simple_relation.md) | `website` | [`URL`](./url.md) | Links the organization to its primary website or one dedicated to a product | +| [`SimpleRelation`](../relations/simple_relation.md) | `social_media_profile` | [`URL`](./url.md) | Links the organization to one of its social media profiles | +| [`SimpleRelation`](../relations/simple_relation.md) | `funding_source` | `Organization`, [`Person`](./person.md) | An `Organization` or `Person` that has invested in this company previously | diff --git a/docs/open_asset_model/assets/tls_certificate.md b/docs/open_asset_model/assets/tls_certificate.md index e69de29..2195dbe 100644 --- a/docs/open_asset_model/assets/tls_certificate.md +++ b/docs/open_asset_model/assets/tls_certificate.md @@ -0,0 +1,102 @@ +# :simple-owasp: TLSCertificate + +The `TLSCertificate` asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents an X.509 certificate used to establish trust in TLS/SSL connections across Internet-facing services. TLS certificates are critical for encrypting traffic, authenticating services, and ensuring secure communication between clients and servers. + +This asset captures detailed metadata about observed certificates, making it possible to track their usage across domains, detect misconfigurations, monitor expiration, and identify shared infrastructure through certificate reuse. By modeling certificates as first-class assets, the OAM enables graph-based analysis of cryptographic trust relationships and their ties to real-world entities and assets. + +Each `TLSCertificate` includes key attributes such as: + +- **Version** – The X.509 version number of the certificate. +- **Serial Number** – A unique identifier assigned by the certificate authority (CA). +- **Subject Common Name (CN)** – The primary identity this certificate claims to represent. +- **Issuer Common Name (CN)** – The identity of the CA that issued the certificate. +- **Validity Period** – Timestamps indicating when the certificate is valid (`not_before`) and when it expires (`not_after`). +- **Key Usage / Extended Key Usage** – Lists of intended purposes for the certificate (e.g., `DigitalSignature`, `ServerAuth`). +- **Signature Algorithm** – The algorithm used by the CA to sign the certificate. +- **Public Key Algorithm** – The algorithm used by the certificate's public key. +- **CA Flag** – A boolean flag indicating whether the certificate is a Certificate Authority. +- **CRL Distribution Points** – URLs where revocation information for the certificate may be retrieved. +- **Subject Key ID / Authority Key ID** – Identifiers used for verifying trust chains and certificate lineage. + +This asset type is commonly used to enrich discovered web services, verify proper encryption practices, and detect certificate sharing across unrelated hosts (e.g., in cloud environments or phishing infrastructure). When linked with assets like `FQDN`, `IPAddress`, or `URL`, `TLSCertificate` helps establish strong associations between services and the organizations operating them. + +## :material-certificate-outline: TLSCertificate Attributes + +| Attributes | Type | Required | Description | +|----------------------------|----------|----------|-------------| +| `version` | string | :material-check-decagram: | The X.509 version of the certificate (e.g., `3`) | +| `serial_number` | string | :material-check-decagram: | Unique serial number assigned by the issuing CA | +| `subject_common_name` | string | :material-check-decagram: | The primary domain or identity the certificate is issued for | +| `issuer_common_name` | string | :material-check-decagram: | The Common Name (CN) of the issuing certificate authority | +| `not_before` | string (datetime) | :material-check-decagram: | Start of the certificate’s validity period | +| `not_after` | string (datetime) | :material-check-decagram: | Expiration of the certificate’s validity period | +| `key_usage` | array of strings | :material-checkbox-blank-circle-outline: | Allowed cryptographic uses (e.g., `DigitalSignature`, `KeyEncipherment`) | +| `ext_key_usage` | array of strings | :material-checkbox-blank-circle-outline: | Extended usage purposes (e.g., `ServerAuth`, `ClientAuth`) | +| `signature_algorithm` | string | :material-checkbox-blank-circle-outline: | Algorithm used to sign the certificate (e.g., `SHA256-RSA`) | +| `public_key_algorithm` | string | :material-checkbox-blank-circle-outline: | Algorithm used in the certificate’s public key (e.g., `RSA`, `ECDSA`) | +| `is_ca` | boolean | :material-checkbox-blank-circle-outline: | Indicates if the certificate is a Certificate Authority | +| `crl_distribution_points` | array of strings | :material-checkbox-blank-circle-outline: | URLs where revocation info can be found | +| `subject_key_id` | string | :material-checkbox-blank-circle-outline: | Identifier for the certificate’s public key | +| `authority_key_id` | string | :material-checkbox-blank-circle-outline: | Identifier for the public key used to sign this certificate | + +## :material-certificate-outline: TLSCertificate Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this TLSCertificate | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this TLSCertificate | + +## :material-certificate-outline: TLSCertificate Outgoing Relations + +```mermaid +graph TD +tls["TLSCertificate"] +fqdn["FQDN"] +fqdnrel@{ shape: braces, label: "common_name +san_dns_name" } +tls --o fqdnrel +fqdnrel --> fqdn + +contact["ContactRecord"] +contactrel@{ shape: braces, label: "subject_contact +issuer_contact" } +tls --o contactrel +contactrel --> contact + +url["URL"] +urlrel@{ shape: braces, label: "san_url +ocsp_server +issuing_certificate_url" } +tls --o urlrel +urlrel --> url + +ipaddr["IPAddress"] +address@{ shape: braces, label: "san_ip_address" } +tls --o address +address --> ipaddr + +ident["Identifier"] +idrel@{ shape: braces, label: "san_email_address" } +tls --o idrel +idrel --> ident + +cert["TLSCertificate"] +issuer@{ shape: braces, label: "issuing_certificate" } +tls --o issuer +issuer --> cert +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `common_name` | [`FQDN`](./fqdn.md) | Links the certificate common name to the `FQDN` asset with that DNS name | +| [`SimpleRelation`](../relations/simple_relation.md) | `subject_contact` | [`ContactRecord`](./contact_record.md) | Links the certificate to subject contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `issuer_contact` | [`ContactRecord`](./contact_record.md) | Links the certificate to issuer contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `san_dns_name` | [`FQDN`](./fqdn.md) | Links the certificate to `FQDN` assets found in the Subject Alternative Name (SAN) field | +| [`SimpleRelation`](../relations/simple_relation.md) | `san_email_address` | [`Identifier`](./identifier.md) | Links the certificate to `Identifier` assets found in the Subject Alternative Name (SAN) field | +| [`SimpleRelation`](../relations/simple_relation.md) | `san_ip_address` | [`IPAddress`](./ip_address.md) | Links the certificate to `IPAddress` assets found in the Subject Alternative Name (SAN) field | +| [`SimpleRelation`](../relations/simple_relation.md) | `san_url` | [`URL`](./url.md) | Links the certificate to `URL` assets found in the Subject Alternative Name (SAN) field | +| [`SimpleRelation`](../relations/simple_relation.md) | `issuing_certificate` | `TLSCertificate` | Links a certificate to the issuing `TLSCertificate` used for signing | +| [`SimpleRelation`](../relations/simple_relation.md) | `issuing_certificate_url` | [`URL`](./url.md) | The `URL` asset where the issuing `TLSCertificate` can be found | +| [`SimpleRelation`](../relations/simple_relation.md) | `ocsp_server` | [`URL`](./url.md) | The OCSP responder that can provide status information regarding the validity of a digital certificate | diff --git a/docs/open_asset_model/assets/url.md b/docs/open_asset_model/assets/url.md index 56751f6..785a93e 100644 --- a/docs/open_asset_model/assets/url.md +++ b/docs/open_asset_model/assets/url.md @@ -1 +1,77 @@ # :simple-owasp: URL + +The `URL` asset type is part of the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) and represents a fully qualified web resource identifier. This asset captures essential information about a Uniform Resource Locator, including its structure, classification, and the context in which it was discovered or used. + +URLs are a central component in external-attack surface assessments, as they often map directly to web applications, APIs, or other internet-facing services. Modeling URLs as first-class assets enables automated analysis, correlation with certificates, subdomain enumeration, and vulnerability scanning workflows. + +Each `URL` asset includes the following attributes: + +- **Raw URL** - The raw and unprocessed URL originally collected. +- **Scheme** – The protocol used (e.g., `http`, `https`). +- **Username** - The username used in HTTP basic authentication. +- **Password** - The password used in HTTP basic authentication. +- **Host** – The domain or IP address portion (e.g., `example.com`). +- **Port** – Optional—explicit port if non-standard (e.g., `8080`). +- **Path** – The resource path on the host (e.g., `/login`). +- **Options** – Extra options used while connecting. +- **Fragment** – Optional—anchor reference within the resource (e.g., `#section`). + +By representing URLs with a dedicated asset structure, OAM supports detailed analysis of web-facing infrastructure—like identifying TLS mismatches, linking subdomains to specific applications, flagging hosts with dynamic or query-based endpoints, and auditing for insecure or deprecated schemes. + +This asset type plays a key role in workflows such as subdomain takeover detection, API fingerprinting, redirect chain mapping, and vulnerability assessment pipelines. + +## :octicons-browser-24: URL Attributes + +| Attributes | Type | Required | Description | +|------------------|--------|----------|-------------| +| `url` | string | :material-check-decagram: | The raw and unprocessed URL originally collected | +| `scheme` | string | :material-check-decagram: | Protocol used in the URL (e.g., `http`, `https`) | +| `username` | string | :material-checkbox-blank-circle-outline: | The username used in HTTP basic authentication | +| `password` | string | :material-checkbox-blank-circle-outline: | The password used in HTTP basic authentication | +| `host` | string | :material-check-decagram: | Domain name or IP address (e.g., `example.com`) | +| `port` | number | :material-checkbox-blank-circle-outline: | Optional non-standard port (e.g., `8443`) | +| `path` | string | :material-checkbox-blank-circle-outline: | The URL path component (e.g., `/admin`) | +| `options` | string | :material-checkbox-blank-circle-outline: | Extra options used while connecting | +| `fragment` | string | :material-checkbox-blank-circle-outline: | Optional fragment identifier (e.g., `#section`) | + +## :octicons-browser-24: URL Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this URL | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this URL | + +## :octicons-browser-24: URL Outgoing Relations + +```mermaid +graph TD +url["URL"] +fqdn["FQDN (e.g. example.com)"] +domain@{ shape: braces, label: "domain" } +url --o domain +domain --> fqdn + +ipaddr["IPAddress"] +address@{ shape: braces, label: "ip_address" } +url --o address +address --> ipaddr + +service["Service"] +port@{ shape: braces, label: "port" } +url --o port +port --> service + +file["File"] +filerel@{ shape: braces, label: "file" } +url --o filerel +filerel --> file +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `domain` | [`FQDN`](./fqdn.md) | Links the URL to the domain name equal to the `host` attribute | +| [`SimpleRelation`](../relations/simple_relation.md) | `ip_address` | [`IPAddress`](./ip_address.md) | Links the URL to the IP address equal to the `host` attribute | +| [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents the port that served up content for this URL | +| [`SimpleRelation`](../relations/simple_relation.md) | `file` | [`File`](./file.md) | Links the URL to the file that was served up at this location | diff --git a/mkdocs.yml b/mkdocs.yml index a52ad82..f97e4aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,6 +120,7 @@ nav: - Assets: - Assets: open_asset_model/assets/index.md - Account: open_asset_model/assets/account.md + - AutonomousSystem: open_asset_model/assets/autonomous_system.md - ContactRecord: open_asset_model/assets/contact_record.md - DomainRecord: open_asset_model/assets/domain_record.md - File: open_asset_model/assets/file.md From 7dd7556b0cbc42f9753e54feb4542b41b0ee75de Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 20:34:14 -0400 Subject: [PATCH 19/45] fixes --- docs/open_asset_model/assets/organization.md | 27 +++++++++----------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 90ba9eb..043ccd4 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -26,15 +26,15 @@ The `Organization` asset enables enrichment and correlation of digital infrastru |--------------------|-------------------|----------|-------------| | `unique_id` | string | :material-check-decagram: | Unique identifier for the organization within the model | | `name` | string | :material-check-decagram: | Common name used to identify the organization | -| `legal_name` | string | :material-check-circle: | Official registered name of the organization | -| `founding_date` | string (date) | :material-check-circle: | Date when the organization was founded (e.g., `2004-09-15`) | -| `jurisdiction` | string | :material-check-circle: | Legal jurisdiction of incorporation (e.g., `US-DE`) | -| `registration_id` | string | :material-check-circle: | Registered entity ID from a business registry | -| `industry` | string | :material-check-circle: | Sector classification (e.g., `Cybersecurity`, `E-Commerce`) | -| `target_markets` | array of strings | :material-check-circle: | Markets or regions the organization serves (e.g., `US`, `EU`) | -| `active` | boolean | :material-check-circle: | Whether the organization is currently active | -| `non_profit` | boolean | :material-check-circle: | Whether the organization is a nonprofit | -| `headcount` | number | :material-check-circle: | Approximate number of employees | +| `legal_name` | string | :material-checkbox-blank-circle-outline: | Official registered name of the organization | +| `founding_date` | string (date) | :material-checkbox-blank-circle-outline: | Date when the organization was founded (e.g., `2004-09-15`) | +| `jurisdiction` | string | :material-checkbox-blank-circle-outline: | Legal jurisdiction of incorporation (e.g., `US-DE`) | +| `registration_id` | string | :material-checkbox-blank-circle-outline: | Registered entity ID from a business registry | +| `industry` | string | :material-checkbox-blank-circle-outline: | Sector classification (e.g., `Cybersecurity`, `E-Commerce`) | +| `target_markets` | array of strings | :material-checkbox-blank-circle-outline: | Markets or regions the organization serves (e.g., `US`, `EU`) | +| `active` | boolean | :material-checkbox-blank-circle-outline: | Whether the organization is currently active | +| `non_profit` | boolean | :material-checkbox-blank-circle-outline: | Whether the organization is a nonprofit | +| `headcount` | number | :material-checkbox-blank-circle-outline: | Approximate number of employees | ## :octicons-organization-24: Organization Properties @@ -43,7 +43,6 @@ The `Organization` asset enables enrichment and correlation of digital infrastru | [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Organization | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Organization | - ## :octicons-organization-24: Organization Outgoing Relations ```mermaid @@ -58,7 +57,7 @@ loc["Location"] locrel@{ shape: braces, label: "legal_address hq_address location" } -tls --o locrel +org --o locrel locrel --> loc org2["Organization"] @@ -83,12 +82,10 @@ member@{ shape: braces, label: "member" } org --o member member --> person -person2["Person"] -org3["Organization"] funding@{ shape: braces, label: "funding_source" } org --o funding -funding --> org3 -funding --> person2 +funding --> org2 +funding --> person ``` --- From 0b538215d564e8d378c35c6747eefb818ff64c7e Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 20:36:47 -0400 Subject: [PATCH 20/45] more fixes --- docs/open_asset_model/assets/organization.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 043ccd4..3b0f2ec 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -100,7 +100,6 @@ funding --> person | [`SimpleRelation`](../relations/simple_relation.md) | `org_unit` | `Organization` | Links the organization to one of its sectors or departments that is externally visible | | [`SimpleRelation`](../relations/simple_relation.md) | `account` | [`Account`](./account.md) | Links the organization to one of its digital or financial accounts | | [`SimpleRelation`](../relations/simple_relation.md) | `member` | [`Person`](./person.md) | Links the organization to one of its employees identified as a `Person` asset | -| [`SimpleRelation`](../relations/simple_relation.md) | `san_ip_address` | [`IPAddress`](./ip_address.md) | Links the certificate to `IPAddress` assets found in the Subject Alternative Name (SAN) field | | [`SimpleRelation`](../relations/simple_relation.md) | `website` | [`URL`](./url.md) | Links the organization to its primary website or one dedicated to a product | | [`SimpleRelation`](../relations/simple_relation.md) | `social_media_profile` | [`URL`](./url.md) | Links the organization to one of its social media profiles | | [`SimpleRelation`](../relations/simple_relation.md) | `funding_source` | `Organization`, [`Person`](./person.md) | An `Organization` or `Person` that has invested in this company previously | From cadb8309df35fb2326ead88c33d82330e3915918 Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 1 Jul 2025 20:40:06 -0400 Subject: [PATCH 21/45] fixed the mermaid graph --- docs/open_asset_model/assets/organization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 3b0f2ec..9405412 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -72,7 +72,7 @@ social_media_profile" } org --o urlrel urlrel --> url -account["Identifier"] +account["Account"] acctrel@{ shape: braces, label: "account" } org --o acctrel acctrel --> account From c440340dadf8262d16a796013af028e1c5cc85b1 Mon Sep 17 00:00:00 2001 From: caffix Date: Wed, 2 Jul 2025 00:38:12 -0400 Subject: [PATCH 22/45] updated --- docs/open_asset_model/assets/identifier.md | 58 ++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/open_asset_model/assets/identifier.md b/docs/open_asset_model/assets/identifier.md index e69de29..06106c3 100644 --- a/docs/open_asset_model/assets/identifier.md +++ b/docs/open_asset_model/assets/identifier.md @@ -0,0 +1,58 @@ +# :simple-owasp: Identifier + +The **Identifier** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a structured, time-aware label used to uniquely reference an asset, entity, or object within or across systems. + +- **Definition:** An `Identifier` includes a unique string (`unique_id`) and a human-readable or system-specific ID value (`id`), along with metadata about its type, lifecycle, and status. It is defined by the following attributes: + - `unique_id`: A globally unique string representing the identifier instance (e.g., a UUID). + - `id`: The actual identifier value, such as a hostname, domain name, serial number, or object ID. + - `id_type`: A label describing the type of identifier (e.g., `arin`, `duns`, `email`, `lei`, etc.). + - `creation_date` *(optional)*: When the identifier was created. + - `update_date` *(optional)*: The most recent update timestamp. + - `expiration_date` *(optional)*: When the identifier is expected to expire or become invalid. + - `status` *(optional)*: The current state of the identifier (e.g., `active`, `expired`, `revoked`). + +- **Purpose:** This asset type provides a standardized way to model references to assets or entities that exist in external systems, databases, or registries. It supports use cases such as identity tracking, configuration management, compliance audits, and historical analysis. + +- **Design Choice:** By separating the identifier’s core value (`id`) from its metadata (such as timestamps and status), the model allows flexible and time-sensitive tracking of identifiers. This enables better integration with asset registries, IAM systems, and third-party feeds while preserving clarity in asset relationships. + +In summary, the `Identifier` asset type captures structured, versioned references to external or internal identifiers, enabling the OAM to model asset identity and traceability across systems and time. + +## :fontawesome-regular-id-card: Identifier Attributes + +| Attributes | Type | Required | Description | +| :---------------: | :-------: | :--------: | :----------- | +| `unique_id` | string | :material-check-decagram: | A globally unique string representing the identifier | +| `id` | string | :material-check-decagram: | The actual identifier value, such as a serial number | +| `id_type` | string | :material-checkbox-blank-circle-outline: | A label describing the type of identifier | +| `creation_date` | string | :material-checkbox-blank-circle-outline: | When the identifier was created | +| `update_date` | string | :material-checkbox-blank-circle-outline: | The most recent update timestamp | +| `expiration_date` | string | :material-checkbox-blank-circle-outline: | When the identifier is expected to become invalid | +| `status` | string | :material-checkbox-blank-circle-outline: | The current state of the identifier | + +## :fontawesome-regular-id-card: Identifier Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Identifier | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Identifier | + +## :fontawesome-regular-id-card: Identifier Outgoing Relations + +```mermaid +graph TD +ident["Identifier"] +contact["ContactRecord"] +allrel@{ shape: braces, label: "issuing_agent +issuing_authority +registration_agency" } +ident --o allrel +allrel --> contact +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `registration_agency` | [`ContactRecord`](./contact_record.md.md) | Links a registration ID with the registering agency | +| [`SimpleRelation`](../relations/simple_relation.md) | `issuing_authority` | [`ContactRecord`](./contact_record.md) | Links an identifier with its issuing authority | +| [`SimpleRelation`](../relations/simple_relation.md) | `issuing_agent` | [`ContactRecord`](./contact_record.md) | Links an identifier with its issuing agent | From 1ecbd0e9a720020f3561f3463e8b502e20b5c188 Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 7 Jul 2025 01:17:49 -0400 Subject: [PATCH 23/45] updated the summary page --- docs/open_asset_model/relations/index.md | 88 +++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/docs/open_asset_model/relations/index.md b/docs/open_asset_model/relations/index.md index c35b34b..8facf5d 100644 --- a/docs/open_asset_model/relations/index.md +++ b/docs/open_asset_model/relations/index.md @@ -1 +1,87 @@ -# :simple-owasp: `Relations` +# :simple-owasp: Relations + +In the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model), a **relation** is a typed, directed connection between two assets that expresses how they are linked in the external world. Relations transform isolated observations into an **interconnected graph**, enabling reasoning over ownership, control, communication, service structure, and many other dimensions. Each relation carries contextual metadata such as discovery source, timestamps, and confidence, and is a first-class citizen in the data model—critical for building a coherent picture of an organization's external footprint. + +## :material-graph-outline: Why *Relations* Matter + +While *assets* are the atomic units of external exposure, **relations** are what make those atoms intelligible as systems. They represent the **structure**, **flow**, and **attribution logic** that connects seemingly disparate observations into a meaningful model. + +Relations bring three core advantages to the OAM: + +1. **Contextual Linking** – Relations encode meaningful semantics (e.g., *announces*, *contains*, *registration*) between assets. +2. **Graph Navigation** – They enable powerful queries such as tracing supply chain dependencies or resolving domain-to-IP mappings. +3. **Explainability** – Each relation retains source, timestamp, and confidence, making inferences and automated decisions transparent and reproducible. + +## :material-graph-outline: Relation Definition + +> **Relation**: *A typed, directional edge connecting two assets that captures a discoverable or inferred relationship between them.* + +Each relation answers three questions: + +1. **What is the connection?** + The **label** (e.g., *dns_record*, *contains*, *owns*, *announces*). +2. **What assets are involved?** + A **source asset** and a **target asset**, each uniquely identified. +3. **When was it discovered?** + A timestamp for when it was first and most recently seen. + +## :material-graph-outline: Core Relation Schema + +```json +{ + "label": "contains", + "source": "Netblock/192.0.2.0-24", + "target": "IPAddress/192.0.2.4", + "created_at": "2025-06-20T14:22:00Z", + "last_seen": "2025-06-20T14:22:00Z", +} +``` + +## :material-graph-outline: Common Relation Labels (Partial) + +| Relation Type | From (Source Asset) | To (Target Asset) | Meaning | +| -------------------- | ------------------- | ------------------------- | ---------------------------- | +| **dns_record** | FQDN | IPAddress | DNS resolved A/AAAA record | +| **contains** | Netblock | IPAddress | IP belongs to CIDR range | +| **announces** | AutonomousSystem | Netblock | AS BGP route announcement | +| **registration** | Netblock | IPNetRecord | Ownership or allocation data | + +*The list is extensible—new relation types are added as threat models and data sources evolve.* + +## :material-graph-outline: Directionality and Semantics + +Relations are **directed**: a relation from *A → B* is not the same as *B → A*. For instance: + +* *FQDN → IPAddress* via `dns_record` indicates resolution; +* *IPAddress → FQDN* is not automatically implied and may require reverse DNS (`ptr_record`). + +Understanding directionality is key to constructing valid traversal paths and interpreting graph queries. + +## :material-graph-outline: Role in Graph Queries + +Relations are the **edges** that enable: + +* Ownership traversal: *Domain → Organization → LegalName* +* Infrastructure mapping: *Service → IP → Netblock → AS* +* Contact pivoting: *TLSCertificate → ContactRecord → Organization* + +The expressive power of the model arises from chaining these relations through triple-based queries. + +Example: + +> *“Which TLS certificates are served from IPs owned by ASNs linked to Acme Corp?”* + +This query may walk: +`Organization → organization → ContactRecord → registrant → AutnumRecord → registration → AutonomousSystem → announces → Netblock → contains → IPAddress → port → Service → certificate → TLSCertificate` + +## :material-graph-outline: Where to Go Next + +Learn more about the structure and usage of the model: + +- [Assets](../assets/index.md) – The core entities in the graph. +- [Properties](../properties/index.md) – Descriptive metadata that enrich assets. +- [Triples](../assetdb/triples.md) – Performing graph queries using SPARQL-style syntax. +- [Assoc Tool](../framework_tools/assoc.md) – Using the command-line tool that queries the graph. +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file From 0a7e8519da9bb60b878e9205fbc763518a5527ad Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 7 Jul 2025 21:13:27 -0400 Subject: [PATCH 24/45] updates --- docs/open_asset_model/assets/account.md | 245 +++++------------- .../assets/autonomous_system.md | 4 + .../open_asset_model/assets/contact_record.md | 4 + docs/open_asset_model/assets/domain_record.md | 69 +++++ docs/open_asset_model/assets/file.md | 52 ++++ docs/open_asset_model/assets/fqdn.md | 4 + .../open_asset_model/assets/funds_transfer.md | 67 +++++ docs/open_asset_model/assets/identifier.md | 4 + docs/open_asset_model/assets/ip_address.md | 4 + docs/open_asset_model/assets/netblock.md | 4 + docs/open_asset_model/assets/organization.md | 4 + docs/open_asset_model/assets/person.md | 66 +++++ docs/open_asset_model/assets/product.md | 66 +++++ .../assets/tls_certificate.md | 4 + docs/open_asset_model/assets/url.md | 4 + .../properties/dns_property.md | 4 + docs/open_asset_model/properties/index.md | 90 ++++++- .../properties/simple_property.md | 4 + .../properties/source_property.md | 4 + .../properties/vuln_property.md | 4 + .../relations/basic_dns_relation.md | 4 + docs/open_asset_model/relations/index.md | 4 +- .../relations/port_relation.md | 4 + .../relations/pref_dns_relation.md | 4 + .../relations/simple_relation.md | 4 + .../relations/srv_dns_relation.md | 4 + 26 files changed, 544 insertions(+), 187 deletions(-) diff --git a/docs/open_asset_model/assets/account.md b/docs/open_asset_model/assets/account.md index 60bc0a9..bf1ee8c 100644 --- a/docs/open_asset_model/assets/account.md +++ b/docs/open_asset_model/assets/account.md @@ -1,211 +1,86 @@ -# :simple-owasp: `Account` +# :simple-owasp: Account -The [`account.go`](https://github.com/owasp-amass/open-asset-model/blob/master/account/account.go) file defines the **Account asset** within the **Open Asset Model**. An **Account** represents a financial or entity-managed asset, such as a **bank account, online payment account, or corporate account**. The model allows accounts to establish structured relationships with **entities (individuals or organizations), funds transfers, and financial identifiers** such as **IBAN and SWIFT** codes. +The `Account` asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a digital or financial account associated with an organization, user, or service. This may include cloud service accounts, financial accounts, email or user login handles, and other forms of identity-linked accounts that hold operational, monetary, or access significance. -## Table of Contents +Each `Account` asset includes structured metadata describing its identity and lifecycle: -- [Overview](#overview) -- [Account Structure](#account-structure) -- [Attributes](#attributes) -- [Implemented Interfaces and Methods](#implemented-interfaces-and-methods) -- [Key()](#key) -- [AssetType()](#assettype) -- [JSON()](#json) -- [Relationship with the Open Asset Model](#relationship-with-the-open-asset-model) -- [Usage](#usage) +- **ID** – A globally unique identifier for the account within the graph. +- **Type** – The kind of account represented (e.g., `email`, `bank`, `cloud`, `user`, `subscription`). +- **Username** – The login handle, screen name, or identifier tied to the account (e.g., `admin@corp.com`, `acme-billing`). +- **Account Number** – An optional unique number assigned to the account (e.g., bank account or customer ID). +- **Balance** – Optional numeric value representing a monetary balance or credit (used primarily for financial contexts). +- **Active** – A boolean indicating whether the account is currently in use or retired. ---- - -## **//** Overview - -The **Account asset** is an integral part of the **Open Asset Model**, designed to support: - -- **Financial & entity-managed accounts** (e.g., bank, corporate, or payment accounts). - -- **Multiple relationships** such as **entity ownership (Person/Organization)** and **fund transfers**. - -- **Standardized data structure** for integration with external financial and asset-tracking systems. - -The **`Account`** struct is designed with **JSON tags for serialization**, ensuring seamless integration with **APIs and structured storage systems**. - ---- - -## **//** Account Structure - -The **`Account`** struct defines key attributes necessary for financial asset representation. - -```go -// Account represents an account managed by an organization. -type Account struct { - ID string `json:"unique_id"` // Unique identifier - Type string `json:"account_type"` // Type of account (e.g., savings, checking) - Username string `json:"username,omitempty"` // Optional username - Number string `json:"account_number,omitempty"` // Account number - Balance float64 `json:"balance,omitempty"` // Account balance - Active bool `json:"active,omitempty"` // Status of the account -} -``` - ---- - -**Attribute Breakdown** - -| **Field Name** | **Type** | **JSON Tag** | **Description** | -|----------------|-----------|------------------------------|--------------------------------------------------------------------------| -| **`ID`** | `string` | `"unique_id"` | **Unique identifier** for the account (used as the **asset key**) | -| **`Type`** | `string` | `"account_type"` | Represents the **type of account** (e.g., savings, checking) | -| **`Username`** | `string` | `"username,omitempty"` | Optional **username** associated with the account | -| **`Number`** | `string` | `"account_number,omitempty"` | Optional **account number** used as a secondary identifier | -| **`Balance`** | `float64` | `"balance,omitempty"` | Represents the **current balance** of the account | -| **`Active`** | `bool` | `"active,omitempty"` | Indicates whether the **account is active** | - ---- - -!!! info " omitempty " - The `omitempty` option in the JSON tags ensures that if a field is empty or its default value, it will be omitted from JSON serialization. This helps keep the data streamlined. - ---- - -## **//** Implemented Interfaces and Methods - -The **`Account` struct** implements the **Asset interface**, ensuring consistency across the **Open Asset Model**. - -### `Key()` - -- **Purpose:** - Returns a unique key (identifier) for the asset. This key is fundamental for distinguishing between different assets. - -- **Implementation:** - - ```go - // Key implements the Asset interface. - func (a Account) Key() string { - return a.ID - } - ``` - **Usage:** - - - Used to **uniquely identify** the account. +- **Definition:** *An identity-linked asset that represents a digital, user, or financial account used to access or control resources across infrastructure or service environments.* - - Serves as the **primary key** for asset indexing and retrieval. +- **Purpose:** The Account asset plays a vital role in representing non-infrastructure access points—especially those tied to identity, privilege, and control. ---- - -### `AssetType()` - -- **Purpose:** - Returns the specific type of the asset within the **Open Asset Model**. - -- **Implementation:** +Key use cases include: - ```go - // AssetType implements the Asset interface. - func (a Account) AssetType() model.AssetType { - return model.Account - } - ``` - **Usage:** +- **Credential Discovery** – Modeling usernames or accounts found in source code, breach data, or service responses. +- **Privilege Mapping** – Associating accounts with specific services or roles in cloud or SaaS environments. +- **Exposure Attribution** – Tracing exposed keys, billing accounts, or cloud identities back to organizations. +- **Operational Monitoring** – Tracking stale or inactive accounts that may indicate shadow IT or abandoned assets. +- **Financial Context** – Enriching infrastructure or access graphs with business-relevant metadata like balances or customer IDs. - - Allows systems to **categorize the asset** as an **`Account`**. +As modern infrastructure increasingly relies on cloud identities, tokens, and user-managed accounts, this asset type ensures these components are treated with the same rigor and visibility as traditional network assets. - - Ensures **type consistency** when processing different asset categories. +- **Design Choice:** The design of the Account asset type is intentionally minimal, yet extensible: ---- - -### `JSON()` +- **Type-Driven Classification** – The account_type field enables generalized modeling (e.g., cloud, user, bank) while allowing tooling to define additional specificity as needed. +- **Dual-Use Fields** – By including both username and account_number, the model supports both identity-driven and numerically indexed account types (e.g., login-based vs. customer-ID-based). +- **Support for Financial Metadata** – The balance field anticipates modeling of assets where monetary value or usage limits play a role (e.g., billing accounts or quota-based services). +- **Lifecycle Awareness** – The active boolean enables visibility into the operational state of the account, useful for spotting dormant, disabled, or legacy identities. -- **Purpose:** - Serializes the **`Account`** struct into **JSON format** for **data exchange and storage**. +This flexible schema supports ingestion from diverse data sources including cloud control planes, threat intelligence feeds, credential scanning tools, and financial systems, making the Account a powerful linking node between people, services, and infrastructure. -- **Implementation:** +Modeling accounts as first-class assets enables reasoning about identity exposure, credential misuse, service abuse, and privilege relationships. Whether discovered via configuration files, leaked credentials, service enumeration, or third-party intelligence, `Account` assets play a key role in mapping the operational footprint and associated risks of an organization. - ```go - // JSON implements the Asset interface. - func (a Account) JSON() ([]byte, error) { - return json.Marshal(a) - } - ``` +Account assets can be linked to services, users, or organizations through relations, enabling workflows such as credential exposure detection, service-to-user mapping, or analysis of abandoned or inactive accounts across cloud providers or infrastructure environments. - **Usage:** +## :material-account: Account Attributes - - Converts the asset into **JSON format** for **APIs, databases, and logging**. +| Attributes | Type | Required. | Description. | +| :-------------------: | :---------: | :----------: | :------------- | +| `unique_id` | string | :material-check-decagram: | Unique identifier for the account within the model | +| `account_type` | string | :material-check-decagram: | Classification of the account (e.g., `cloud`, `bank`, `user`) | +| `username` | string | :material-checkbox-blank-circle-outline: | Login name, email, or screen name associated with the account | +| `account_number` | string | :material-checkbox-blank-circle-outline: | Optional numeric or alphanumeric account ID (e.g., `acct-1234`) | +| `balance` | float | :material-checkbox-blank-circle-outline: | Optional financial or credit balance | +| `active` | boolean | :material-checkbox-blank-circle-outline: | Whether the account is currently active | - - Enables **data transmission** across services. - ---- +## :material-account: Account Properties -## **//** Relationship with the Open Asset Model - -The **Open Asset Model** provides a standardized approach to handling digital and physical assets. The **`Account`** asset is a critical component and supports: - -- **User Entities**: Representing **Persons or Organizations** that own the account. - -- **Funds Transfers**: Tracking **financial transactions** between accounts. - -- **Banking Identifiers**: Supporting **IBAN and SWIFT codes** for financial integration. - -By adhering to these relationships, the **`Account model`** ensures structured data exchange between **security, financial, and asset management systems**. - ---- +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Account | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Account | -## **//** Usage +## :material-account: Account Outgoing Relations -The **Open Asset Model** provides structured asset management for accounts. +```mermaid +graph TD +acct["Account"] +ident["Identifier"] +idRel@{ shape: braces, label: "id"} +acct --o idRel +idRel --> ident -Below is an example demonstrating how to: - -- **Retrieve account details**. - -- **Serialize an account to JSON**. - -```go -package main - -import ( - "encoding/json" - "fmt" - "github.com/owasp-amass/open-asset-model/account" -) - -func main() { - // Define an example account asset - acc := account.Account{ - ID: "acc-12345", - Type: "Savings", - Username: "johndoe", - Number: "987654321", - Balance: 1500.75, - Active: true, - } - - // Serialize the account to JSON - jsonData, err := acc.JSON() - if err != nil { - fmt.Println("Error serializing account to JSON:", err) - return - } - - fmt.Printf("Account Type: %s\n", acc.Type) - fmt.Printf("Serialized JSON: %s\n", string(jsonData)) -} +org["Organization"] +person["Person] +user@{ shape: braces, label: "user"} +acct --o user +user --> org +user --> persom ``` --- -## **//** Summary +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :---------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the account to other discovered identifiers | +| [`SimpleRelation`](../relations/simple_relation.md) | `user` | [`Organization`](./organization.md), [`Person`](./person.md) | Links the account to known users that have access | -The **`account.go`** file is a fundamental part of the **Open Asset Model**, ensuring structured and standardized management of **financial and user-managed accounts**. - -Key takeaways: - -- **Defines an `Account` struct** that represents various financial accounts. - -- **Implements the Asset interface** to ensure consistency. - -- Supports relationships with **user entities, financial transactions, and banking identifiers**. - -- Provides **JSON serialization** for easy data exchange. - -By following this structured approach, **contributors** can extend account functionality, while **users** can efficiently manage financial assets in their security and asset intelligence workflows. +--- ---- \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/autonomous_system.md b/docs/open_asset_model/assets/autonomous_system.md index 853e92d..3cea87d 100644 --- a/docs/open_asset_model/assets/autonomous_system.md +++ b/docs/open_asset_model/assets/autonomous_system.md @@ -45,3 +45,7 @@ regrel --> autnum | :-----------------: | :----------------: | :--------------: | :------------ | | [`SimpleRelation`](../relations/simple_relation.md) | `announces` | [`Netblock`](./netblock.md) | Links an IPAddress to its DNS name used in PTR records | | [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`AutnumRecord`](./autnum_record.md) | Links a ASN to its associated registration data | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/contact_record.md b/docs/open_asset_model/assets/contact_record.md index cf56f6c..8cf68e3 100644 --- a/docs/open_asset_model/assets/contact_record.md +++ b/docs/open_asset_model/assets/contact_record.md @@ -62,3 +62,7 @@ simple6 --> url | [`SimpleRelation`](../relations/simple_relation.md) | `person` | [`Person`](#person) | Represents a person's name discovered with the contact information | | [`SimpleRelation`](../relations/simple_relation.md) | `phone` | [`Phone`](#phone) | Represents a phone number in the contact information | | [`SimpleRelation`](../relations/simple_relation.md) | `url` | [`URL`](#url) | Represents an URL discovered in the contact information | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/domain_record.md b/docs/open_asset_model/assets/domain_record.md index d3f5a12..62f17ac 100644 --- a/docs/open_asset_model/assets/domain_record.md +++ b/docs/open_asset_model/assets/domain_record.md @@ -1 +1,70 @@ +# :simple-owasp: DomainRecord +The **DomainRecord** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) captures authoritative *registration* data for a domain name, as supplied by WHOIS, RDAP, or similar registry services. Domain registration facts are distinct from DNS‑resolution facts; they reveal **who controls a domain, when it was created, and under what status it currently operates**—all of which are vital to attribution, supply‑chain mapping, and domain‑lifecycle monitoring. + +- **Definition:** A `DomainRecord` represents a single domain’s registration record (raw and parsed), including key lifecycle dates, status flags, registrar details, internationalisation fields, and a DNSSEC indicator. + +- **Purpose:** Modeling registration data as a first‑class asset allows security teams to (1) link domains to legal entities and contacts, (2) detect newly registered or expiring domains, (3) follow ownership changes over time, and (4) correlate punycode / IDN variants that could be abused for impersonation. + +- **Design Choice:** Keeping both *normalised* fields (e.g., `created_date`) **and** the original `raw` text preserves machine‑readable consistency while ensuring full auditability. Optional fields make the structure tolerant of incomplete WHOIS responses, and the `status` array supports the many ICANN/ccTLD state strings without schema changes. + +## :material-dns: DomainRecord Attributes + +| Attributes | Type | Required | Description | +| :---------------: | :-----------------: | :------: | :---------- | +| `domain` | string | :material-check-decagram: | Fully‑qualified domain (e.g., `example.com`) | +| `punycode` | string | :material-checkbox-blank-circle-outline: | ASCII form of an IDN (e.g., `xn--exmple‑cua.com`) | +| `name` | string | :material-checkbox-blank-circle-outline: | Second‑level label (`example` in `example.com`) | +| `extension` | string | :material-checkbox-blank-circle-outline: | TLD (`com`, `org`, `io`, …) | +| `whois_server` | string | :material-checkbox-blank-circle-outline: | Hostname or URL of the authoritative WHOIS server | +| `created_date` | string (date) | :material-checkbox-blank-circle-outline: | First registration date | +| `updated_date` | string (date) | :material-checkbox-blank-circle-outline: | Last modification date | +| `expiration_date` | string (date) | :material-checkbox-blank-circle-outline: | Scheduled expiration date | +| `status` | array \ | :material-checkbox-blank-circle-outline: | Registry status codes (`clientTransferProhibited`, …) | +| `dnssec` | boolean | :material-checkbox-blank-circle-outline: | `true` if a DS record is present | +| `raw` | string | :material-checkbox-blank-circle-outline: | Unparsed WHOIS / RDAP text for auditing | +| `id` | string | :material-checkbox-blank-circle-outline: | Optional registry‑specific object ID | + +## :material-dns: DomainRecord Properties + +| Property Type | Property Name | Description | +| :-----------: | :-----------: | :---------- | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Timestamp of the most recent WHOIS/RDAP pull | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Identifies which discovery module produced the record | + +## :material-dns: DomainRecord Outgoing Relations + +```mermaid +graph TD +domrec["DomainRecord"] +fqdn["FQDN"] +names@{ shape: braces, label: "name_server +whois_server" } +domrec --o names +names --> fqdn + +contact["ContactRecord"] +contactrel@{ shape: braces, label: "registrar_contact +registrant_contact +admin_contact +technical_contact +billing_contact" } +domrec --o contactrel +contactrel --> contact +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `name_server` | [`FQDN`](./fqdn.md) | Links the domain registration information with the correct DNS nameserver | +| [`SimpleRelation`](../relations/simple_relation.md) | `whois_server` | [`FQDN`](./fqdn.md) | Links the domain registration information with the correct WHOIS server | +| [`SimpleRelation`](../relations/simple_relation.md) | `registrar_contact` | [`ContactRecord`](./contact_record.md) | Links the domain registration information with registrar contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `registrant_contact` | [`ContactRecord`](./contact_record.md) | Links the domain registration information with registrant contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `admin_contact` | [`ContactRecord`](./contact_record.md) | Links the domain registration information with admin contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `technical_contact` | [`ContactRecord`](./contact_record.md) | Links the domain registration information with contact information of technical personnel | +| [`SimpleRelation`](../relations/simple_relation.md) | `billing_contact` | [`ContactRecord`](./contact_record.md) | Links the domain registration information with contact information of billing personnel | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/file.md b/docs/open_asset_model/assets/file.md index e69de29..db040b7 100644 --- a/docs/open_asset_model/assets/file.md +++ b/docs/open_asset_model/assets/file.md @@ -0,0 +1,52 @@ +# :simple-owasp: File + +The **File** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a file that is publicly accessible from the internet—typically retrieved via HTTP, HTTPS, or other remote protocols. This includes web-accessible files such as JavaScript libraries, PDF documents, configuration exports, or exposed archives. + +- **Definition:** A `File` asset consists of a direct URL reference to a downloadable or inspectable file, with optional metadata such as file name and type. It serves as an abstraction for discrete, remotely hosted resources. + +- **Purpose:** Exposed files often contain valuable signals for OSINT and security teams. Public-facing files may reveal application behavior (e.g., JavaScript logic), data leakage (e.g., exports, backups), infrastructure clues (e.g., `.env`, `.git/config`), or user-generated content (e.g., uploaded resumes, invoices). Modeling these files as assets enables targeted analysis, attribution, and monitoring. + +- **Design Choice:** The `File` type is intentionally simple—centered on its URL—to support lightweight ingestion from crawlers, link resolvers, or passive intelligence feeds. Optional `name` and `type` fields allow for basic classification without requiring full content analysis or mime-type parsing during collection. + +## :material-file-outline: File Attributes + +| Attributes | Type | Required | Description | +|:----------:|:------:|:--------:|:------------| +| `url` | string | :material-check-decagram: | Fully qualified URL to the file (e.g., `https://example.com/.git/config`) | +| `name` | string | :material-checkbox-blank-circle-outline: | Optional file name or basename extracted from the URL | +| `type` | string | :material-checkbox-blank-circle-outline: | Optional file type or format hint (e.g., `pdf`, `js`, `zip`) | + +## :material-file-outline: File Properties + +| Property Type | Property Name | Description | +|:-------------:|:-------------:|:------------| +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this File | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this File | + +## :material-file-outline: File Outgoing Relations + +```mermaid +graph TD +file["File (https://example.com/.git/config)"] +url["URL"] +urlRel@{ shape: braces, label: "url" } +file --o urlRel +urlRel --> url + +contactrec["ContactRecord"] +contains@{ shape: braces; label: "contains" } +file --o contains +contains --> contactrec +contains --> url +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `url` | [`URL`](./url.md) | Links the location of the File into the greater graph | +| [`SimpleRelation`](../relations/simple_relation.md) | `contains` | [`ContactRecord`](./contact_record.md), [`URL`](./url.md) | Links content discovered in the File into the greater graph | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 8388566..0ac1f1e 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -73,3 +73,7 @@ regrel --> domrec | [`SimpleRelation`](../relations/simple_relation.md) | `node` | `FQDN` | Links a DNS zone apex to nodes within the zone | | [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents a port at the FQDN with a responding service | | [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`DomainRecord`](./domain_record.md) | Links a root domain to its associated registration data | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/funds_transfer.md b/docs/open_asset_model/assets/funds_transfer.md index e69de29..298af50 100644 --- a/docs/open_asset_model/assets/funds_transfer.md +++ b/docs/open_asset_model/assets/funds_transfer.md @@ -0,0 +1,67 @@ +# :simple-owasp: FundsTransfer + +The **FundsTransfer** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents the movement of funds between two financial accounts. These transfers may occur via wire, ACH, cryptocurrency, internal bank movement, or other mechanisms that involve the exchange of currency between accounts or organizations. + +- **Definition:** A `FundsTransfer` asset models a single financial transaction involving a specific amount of money, a method of transfer, a currency type, and optionally, reference and exchange data. + +- **Purpose:** Including `FundsTransfer` in the asset model enables reasoning about **financial flows**, which can assist in analyzing operational patterns, detecting anomalies, or tracing value exchanges between entities. When connected to `Account` assets, it supports graph-based queries that explore supply chains, fraud trails, and inter-organizational dependencies. + +- **Design Choice:** This type focuses on capturing the *structure* of a transfer (e.g., amount, method, and timing) rather than sensitive or regulated content (like full account numbers). Optional fields like `exchange_rate` allow the model to support cross-currency scenarios and future integration with financial intelligence tooling, while keeping the core schema minimal and auditable. + +## :material-cash-multiple: FundsTransfer Attributes + +| Attributes | Type | Required | Description | +|:------------------:|:--------:|:--------:|:------------| +| `unique_id` | string | :material-check-decagram: | Unique identifier for the transaction | +| `amount` | float | :material-check-decagram: | Monetary value of the transfer | +| `reference_number` | string | :material-checkbox-blank-circle-outline: | Transaction reference code (e.g., SWIFT, internal ID) | +| `currency` | string | :material-checkbox-blank-circle-outline: | ISO 4217 currency code (e.g., `USD`, `EUR`, `BTC`) | +| `transfer_method` | string | :material-checkbox-blank-circle-outline: | Method used (e.g., `wire`, `ACH`, `crypto`) | +| `exchange_date` | string | :material-checkbox-blank-circle-outline: | Date when currency exchange (if any) occurred | +| `exchange_rate` | float | :material-checkbox-blank-circle-outline: | Rate used for currency conversion, if applicable | + +## :material-cash-multiple: FundsTransfer Properties + +| Property Type | Property Name | Description | +|:-------------:|:-------------:|:------------| +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this FundsTransfer | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this FundsTransfer | + +## :material-cash-multiple: FundsTransfer Outgoing Relations + +```mermaid +graph TD +transfer["FundsTransfer ($5,000 USD)"] +ident["Identifer"] +idRel@{ shape, braces; label: "id" } +transfer --o idRel +idRel --> ident + +acct1["Account (acct-123)"] +fromRel@{ shape: braces; label: "sender" } +transfer --o fromRel +fromRel --> acct1 + +acct2["Account (acct-456)"] +toRel@{ shape: braces; label: "recipient" } +transfer --o toRel +toRel --> acct2 + +org["Organization"] +third@{ shape: braces; label: "third_party" } +transfer --o third +third --> org +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the FundsTransfer to `Identifier` assets, such as confirmation numbers | +| [`SimpleRelation`](../relations/simple_relation.md) | `sender` | [`Account`](./account.md) | Links the FundsTransfer to the `Account` that sent the funds | +| [`SimpleRelation`](../relations/simple_relation.md) | `recipient` | [`Account`](./account.md) | Links the FundsTransfer to the `Account` that received the funds | +| [`SimpleRelation`](../relations/simple_relation.md) | `third_party` | [`Organization`](./organization.md) | A third-party sender that initiates a funds transfer on behalf of another party | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/identifier.md b/docs/open_asset_model/assets/identifier.md index 06106c3..cf6e42e 100644 --- a/docs/open_asset_model/assets/identifier.md +++ b/docs/open_asset_model/assets/identifier.md @@ -56,3 +56,7 @@ allrel --> contact | [`SimpleRelation`](../relations/simple_relation.md) | `registration_agency` | [`ContactRecord`](./contact_record.md.md) | Links a registration ID with the registering agency | | [`SimpleRelation`](../relations/simple_relation.md) | `issuing_authority` | [`ContactRecord`](./contact_record.md) | Links an identifier with its issuing authority | | [`SimpleRelation`](../relations/simple_relation.md) | `issuing_agent` | [`ContactRecord`](./contact_record.md) | Links an identifier with its issuing agent | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/ip_address.md b/docs/open_asset_model/assets/ip_address.md index 072dce5..17ad781 100644 --- a/docs/open_asset_model/assets/ip_address.md +++ b/docs/open_asset_model/assets/ip_address.md @@ -48,3 +48,7 @@ port --> service | :-----------------: | :----------------: | :--------------: | :------------ | | [`SimpleRelation`](../relations/simple_relation.md) | `ptr_record` | [`FQDN`](./fqdn.md) | Links an IPAddress to its DNS name used in PTR records | | [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents a port at the IPAddress with a responding service | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/netblock.md b/docs/open_asset_model/assets/netblock.md index a76bd28..83df138 100644 --- a/docs/open_asset_model/assets/netblock.md +++ b/docs/open_asset_model/assets/netblock.md @@ -46,3 +46,7 @@ regrel --> iprec | :-----------------: | :----------------: | :--------------: | :------------ | | [`SimpleRelation`](../relations/simple_relation.md) | `contains` | [`IPAddress`](./ip_address.md) | Links a Netblock to an IPAddress within the CIDR range | | [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`IPNetRecord`](./ipnet_record.md) | Links a network to its associated registration data | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 9405412..34f0536 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -103,3 +103,7 @@ funding --> person | [`SimpleRelation`](../relations/simple_relation.md) | `website` | [`URL`](./url.md) | Links the organization to its primary website or one dedicated to a product | | [`SimpleRelation`](../relations/simple_relation.md) | `social_media_profile` | [`URL`](./url.md) | Links the organization to one of its social media profiles | | [`SimpleRelation`](../relations/simple_relation.md) | `funding_source` | `Organization`, [`Person`](./person.md) | An `Organization` or `Person` that has invested in this company previously | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/person.md b/docs/open_asset_model/assets/person.md index 8b13789..7ef1e01 100644 --- a/docs/open_asset_model/assets/person.md +++ b/docs/open_asset_model/assets/person.md @@ -1 +1,67 @@ +# :simple-owasp: Person +The **Person** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents an individual human being discovered as part of intelligence collection, attribution, or enrichment processes. Persons may appear in public records, domain registrations, technical contacts, breached datasets, or OSINT sources and often serve as pivots for understanding organizational relationships or behavioral patterns. + +- **Definition:** A `Person` asset encapsulates identifying attributes such as full legal name, date of birth, and gender. It may represent a registrant, technical contact, executive, threat actor, or any other discovered individual. + +- **Purpose:** Modeling people as structured assets allows for attribution graphs, ownership resolution, and behavioral correlation across disparate data points. Individuals are often central to understanding the provenance, intent, or organizational structure behind assets like domains, IP ranges, or certificates. + +- **Design Choice:** The `Person` structure includes multiple levels of name granularity to enable flexible matching and entity resolution. Optional fields (e.g., `birth_date`, `gender`) support deeper analysis when present, but are not required—ensuring compatibility with incomplete or privacy-preserving sources. The model avoids sensitive personal information (e.g., national IDs) unless already exposed via legitimate public data sources. + +## :material-account: Person Attributes + +| Attributes | Type | Required | Description | +|:--------------:|:------:|:--------:|:------------| +| `unique_id` | string | :material-check-decagram: | Unique identifier for the person asset | +| `full_name` | string | :material-check-decagram: | Complete name string (e.g., `"Jane Elizabeth Smith"`) | +| `first_name` | string | :material-check-decagram: | Given name or forename | +| `middle_name` | string | :material-checkbox-blank-circle-outline: | Optional middle name(s) or initials | +| `family_name` | string | :material-check-decagram: | Surname or last name | +| `birth_date` | string | :material-checkbox-blank-circle-outline: | Optional date of birth (ISO format) | +| `gender` | string | :material-checkbox-blank-circle-outline: | Optional gender descriptor (e.g., `female`, `nonbinary`) | + +## :material-account: Person Properties + +| Property Type | Property Name | Description | +|:-------------:|:-------------:|:------------| +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Person | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Person | + +## :material-account: Person Outgoing Relations + +```mermaid +graph TD +person["Person (Jane E. Smith)"] +ident["Identifier"] +idRel@{ shape: braces; label: "id" } +person --o idRel +idRel --> ident + +loc["Location (Street Address)"] +locRel@{ shape: braces; label: "address" } +person --o locRel +locRel --> loc + +phone["Phone"] +phoneRel@{ shape: braces; label: "phone" } +person --o phoneRel +phoneRel --> phone + +acct["Account"] +account@{ shape: braces; label: "account" } +person --o account +account --> acct +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the `Person` to another `Identifier`, such as a maiden name | +| [`SimpleRelation`](../relations/simple_relation.md) | `address` | [`Location`](./location.md) | Links the `Person` to a discovered street address | +| [`SimpleRelation`](../relations/simple_relation.md) | `phone` | [`Phone`](./phone.md) | Links the `Person` to a discovered phone number, such as a cell phone | +| [`SimpleRelation`](../relations/simple_relation.md) | `account` | [`Account`](./account.md) | An account owned or used by the Person, such as an email account | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/product.md b/docs/open_asset_model/assets/product.md index e69de29..a31bb11 100644 --- a/docs/open_asset_model/assets/product.md +++ b/docs/open_asset_model/assets/product.md @@ -0,0 +1,66 @@ +# :simple-owasp: Product + +The **Product** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a commercial or open-source technology product—hardware, software, or service—that plays a role in an organization's external attack surface. Products may include server software, security appliances, cloud services, content management systems, networking gear, and more. + +- **Definition:** A `Product` asset includes a name, type, optional category and description, and optionally a country of origin. It represents a distinct technology offering as discovered in intelligence collection, vulnerability data, or infrastructure enumeration. + +- **Purpose:** Modeling products as first-class assets allows the OAM to associate technologies with organizations, services, or infrastructure. This helps analysts answer questions like “What products are deployed by this organization?”, “Where are certain technologies concentrated?”, or “Is this vulnerable product version publicly exposed?” + +- **Design Choice:** The `Product` structure is intentionally minimal to support broad applicability. While the `ProductRelease` handles additional information such as version, vendor, and licensing via `Identifier` assets and properties, the core type emphasizes identification and categorization. The inclusion of `country_of_origin` supports use cases related to supply chain risk and regulatory compliance. + +## :material-package-variant: Product Attributes + +| Attributes | Type | Required | Description | +|:------------------:|:------:|:--------:|:------------| +| `unique_id` | string | :material-check-decagram: | Unique identifier for the product asset | +| `product_name` | string | :material-check-decagram: | Name of the product (e.g., `nginx`, `Apache Tomcat`, `Zoom`) | +| `product_type` | string | :material-check-decagram: | General type (`software`, `hardware`, `service`, etc.) | +| `category` | string | :material-checkbox-blank-circle-outline: | Optional category (e.g., `web_server`, `load_balancer`, `crm`) | +| `description` | string | :material-checkbox-blank-circle-outline: | Optional short description of the product | +| `country_of_origin`| string | :material-checkbox-blank-circle-outline: | Optional ISO country code or name (e.g., `US`, `Germany`) | + +## :material-package-variant: Product Properties + +| Property Type | Property Name | Description | +|:-------------:|:-------------:|:------------| +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Product | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Product | + +## :material-package-variant: Product Outgoing Relations + +```mermaid +graph TD +product["Product (nginx)"] +ident["Identifier"] +idRel@{ shape: braces; label: "id" } +product --o idRel +idRel --> ident + +org["Organization"] +vendorRel@{ shape: braces; label: "manufacturer" } +product --o vendorRel +vendorRel --> org + +url["URL"] +website@{ shape: braces; label: "website" } +product --o website +website --> url + +prodrel["ProductRelease"] +release@{ shape: braces; label: "release" } +product --o release +release --> prodrel +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the Product to `Identifier` assets, such as product identifiers | +| [`SimpleRelation`](../relations/simple_relation.md) | `manufacturer` | [`Organization`](./organization.md) | The organization that produces and supports the product | +| [`SimpleRelation`](../relations/simple_relation.md) | `website` | [`URL`](./url.md) | The website where information can be found about the product | +| [`SimpleRelation`](../relations/simple_relation.md) | `release` | [`ProductRelease`](./product_release.md) | Links the Product to known product releases and versions | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/tls_certificate.md b/docs/open_asset_model/assets/tls_certificate.md index 2195dbe..0541f23 100644 --- a/docs/open_asset_model/assets/tls_certificate.md +++ b/docs/open_asset_model/assets/tls_certificate.md @@ -100,3 +100,7 @@ issuer --> cert | [`SimpleRelation`](../relations/simple_relation.md) | `issuing_certificate` | `TLSCertificate` | Links a certificate to the issuing `TLSCertificate` used for signing | | [`SimpleRelation`](../relations/simple_relation.md) | `issuing_certificate_url` | [`URL`](./url.md) | The `URL` asset where the issuing `TLSCertificate` can be found | | [`SimpleRelation`](../relations/simple_relation.md) | `ocsp_server` | [`URL`](./url.md) | The OCSP responder that can provide status information regarding the validity of a digital certificate | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/url.md b/docs/open_asset_model/assets/url.md index 785a93e..dae5d92 100644 --- a/docs/open_asset_model/assets/url.md +++ b/docs/open_asset_model/assets/url.md @@ -75,3 +75,7 @@ filerel --> file | [`SimpleRelation`](../relations/simple_relation.md) | `ip_address` | [`IPAddress`](./ip_address.md) | Links the URL to the IP address equal to the `host` attribute | | [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents the port that served up content for this URL | | [`SimpleRelation`](../relations/simple_relation.md) | `file` | [`File`](./file.md) | Links the URL to the file that was served up at this location | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/properties/dns_property.md b/docs/open_asset_model/properties/dns_property.md index 0262e81..d52b7e8 100644 --- a/docs/open_asset_model/properties/dns_property.md +++ b/docs/open_asset_model/properties/dns_property.md @@ -22,3 +22,7 @@ By modeling DNS data with a dedicated property type, `DNSRecordProperty` enables | `header.class` | number | :material-checkbox-blank-circle-outline: | 1, IN class (Internet), is the most commonly used | | `header.ttl` | number | :material-checkbox-blank-circle-outline: | Specifies how long a DNS record should be cached | | `data` | string | :material-check-decagram: | The value from the data field of the DNS resource record | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/properties/index.md b/docs/open_asset_model/properties/index.md index 3e47632..6a3e0da 100644 --- a/docs/open_asset_model/properties/index.md +++ b/docs/open_asset_model/properties/index.md @@ -1 +1,89 @@ -# :simple-owasp: `Properties` +# :simple-owasp: Properties + +In the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model), a **property** is a typed, descriptive annotation attached to an asset or relation. Properties enrich the graph with granular metadata—timestamps, names, identifiers, classifications, fingerprints, and other scalar or structured values—without altering the core topology of the asset graph. + +Properties are **first-class elements** of the model. They provide the facts that support inferences, highlight critical traits, and enable high-resolution filtering or grouping of graph data. Each property is tied to the context in which it was discovered, and many include source attribution for traceability. + +## :material-database-outline: Why *Properties* Matter + +If assets are the **nouns** and relations are the **verbs** of the graph, then **properties are the adjectives**. They give each node and edge its character. + +Properties bring three core advantages to the OAM: + +1. **Precision** – Properties allow representation of fine-grained detail like last time enumerated and confidence score of evidence. +2. **Traceability** – Many property types (e.g., `SourceProperty`, `DNSRecordProperty`) retain the discovery method and timestamp. +3. **Flexibility** – Because properties are modular and loosely typed, new data can be integrated without schema migrations. + +## :material-graph-outline: Property Definition + +> **Property**: *A typed key-value annotation attached to an asset or relation, used to describe a specific observable or characteristic.* + +Each property answers three questions: + +1. **What kind of information is this?** + The **type** (e.g., `SimpleProperty`, `DNSRecordProperty`, `VulnProperty`). + +2. **What does it say?** + A **key-value pair** or structured object expressing some fact about the asset. + +3. **Where did it come from?** + Optional **source metadata**, such as the tool, timestamp, or confidence level. + +## :material-graph-outline: Core Property Types + +| Property Type | Purpose | Example Use Case | +|-----------------------|----------------------------------------------|------------------| +| `SimpleProperty` | Generic key-value metadata | Tag a domain with `last_monitored = 2025-06-20` | +| `SourceProperty` | Key-value pair with discovery context | Tag an IP with `whois_country = US` from RDAP | +| `DNSRecordProperty` | Structured DNS lookup result | Record an `A` record resolution for an FQDN | +| `VulnProperty` | Basic vulnerability data | Attach `CVE-2023-1234` to a service asset | + +Each property is evaluated in the context of its parent asset or relation and contributes to filtering, scoring, reporting, and pivot logic within the model. + +## :material-graph-outline: Property Schema (Conceptually) + +Example of a basic `SourceProperty` attached to an `IPAddress`: + +```json +{ + "type": "SourceProperty", + "name": "RDAP", + "confidence": 75, +} +``` + +Example of a DNSRecordProperty on an FQDN: + +```json +{ + "type": "DNSRecordProperty", + "property_name": "dns_record", + "header": { + "rr_type": 6, + "class": 1, + "ttl": 86400, + }, + "data": "example.com. 86400 IN SOA ns1.example.com. admin.example.com.", +} +``` + +## :material-graph-outline: Properties in Graph Queries + +Properties are not directly navigable edges, but they are critical for filtering and analysis. They can be used in: + +assoc queries to filter assets by specific values. + +Temporal analysis to find stale, newly discovered, or frequently updated assets. + +## :material-graph-outline: Where to Go Next + +Explore the types of data used to enrich and explain assets in the graph: + +- [Assets](../assets/index.md) – The core entities in the graph. +- [Relations](../relations/index.md) – Overview of Relations in the Open Asset Model. +- [Triples](../assetdb/triples.md) – Performing graph queries using SPARQL-style syntax. +- [Assoc Tool](../framework_tools/assoc.md) – Using the command-line tool that queries the graph. + +--- + +© 2025 Jeff Foley — Licensed under Apache 2.0. \ No newline at end of file diff --git a/docs/open_asset_model/properties/simple_property.md b/docs/open_asset_model/properties/simple_property.md index ebd6de6..f0f6a27 100644 --- a/docs/open_asset_model/properties/simple_property.md +++ b/docs/open_asset_model/properties/simple_property.md @@ -19,3 +19,7 @@ In practice, `SimpleProperty` entries are often used when importing information | :--------------: | :-------: | :--------: | :----------- | | `property_name` | string | :material-check-decagram: | A string that identifies the nature or role of the property | | `property_value` | string | :material-check-decagram: | A string-encoded representation of the property's actual value | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/properties/source_property.md b/docs/open_asset_model/properties/source_property.md index 5da1412..3face53 100644 --- a/docs/open_asset_model/properties/source_property.md +++ b/docs/open_asset_model/properties/source_property.md @@ -19,3 +19,7 @@ All Amass engine plugins mark discovered assets and associations between them wi | :--------------: | :-------: | :--------: | :----------- | | `name` | string | :material-check-decagram: | Name of the engine plugin that discovered the asset or relation | | `confidence` | number | :material-checkbox-blank-circle-outline: | A value 0 through 100 representing the confidence percentage | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/properties/vuln_property.md b/docs/open_asset_model/properties/vuln_property.md index 2eeffed..5a0e34f 100644 --- a/docs/open_asset_model/properties/vuln_property.md +++ b/docs/open_asset_model/properties/vuln_property.md @@ -25,3 +25,7 @@ By standardizing how vulnerability metadata is attached to assets and relations, | `category` | string | :material-checkbox-blank-circle-outline: | A general classification of the vulnerability (e.g., `software-vuln`) | | `enum` | string | :material-checkbox-blank-circle-outline: | The taxonomy or enumeration system used (e.g., `CVE`, `CWE`) | | `ref` | string | :material-checkbox-blank-circle-outline: | An optional reference URL for more information about the vulnerability | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/relations/basic_dns_relation.md b/docs/open_asset_model/relations/basic_dns_relation.md index aa5dd62..30007e1 100644 --- a/docs/open_asset_model/relations/basic_dns_relation.md +++ b/docs/open_asset_model/relations/basic_dns_relation.md @@ -24,3 +24,7 @@ In summary, `BasicDNSRelation` enables efficient modeling of essential DNS relat | Property Type | Property Name | Description | | :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this BasicDNSRelation | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/relations/index.md b/docs/open_asset_model/relations/index.md index 8facf5d..890ba02 100644 --- a/docs/open_asset_model/relations/index.md +++ b/docs/open_asset_model/relations/index.md @@ -25,7 +25,7 @@ Each relation answers three questions: 3. **When was it discovered?** A timestamp for when it was first and most recently seen. -## :material-graph-outline: Core Relation Schema +## :material-graph-outline: Core Relation Schema (Conceptually) ```json { @@ -37,6 +37,8 @@ Each relation answers three questions: } ``` +See specific relation types for actual JSON field names. Also, see the [Assoc Tool](../framework_tools/assoc.md) and [Triples](../assetdb/triples.md) for more information regarding how to query the data collected. + ## :material-graph-outline: Common Relation Labels (Partial) | Relation Type | From (Source Asset) | To (Target Asset) | Meaning | diff --git a/docs/open_asset_model/relations/port_relation.md b/docs/open_asset_model/relations/port_relation.md index 2568729..5e24c40 100644 --- a/docs/open_asset_model/relations/port_relation.md +++ b/docs/open_asset_model/relations/port_relation.md @@ -23,3 +23,7 @@ In essence, `PortRelation` adds precise network exposure context to the OAM, let | Property Type | Property Name | Description | | :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this PortRelation | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/relations/pref_dns_relation.md b/docs/open_asset_model/relations/pref_dns_relation.md index 13097df..668e3b6 100644 --- a/docs/open_asset_model/relations/pref_dns_relation.md +++ b/docs/open_asset_model/relations/pref_dns_relation.md @@ -25,3 +25,7 @@ In summary, `PrefDNSRelation` extends basic DNS modeling by introducing priority | Property Type | Property Name | Description | | :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this PrefDNSRelation | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/relations/simple_relation.md b/docs/open_asset_model/relations/simple_relation.md index 1455816..34f60f8 100644 --- a/docs/open_asset_model/relations/simple_relation.md +++ b/docs/open_asset_model/relations/simple_relation.md @@ -21,3 +21,7 @@ In essence, the `SimpleRelation` is a clean, minimal tool used within the OAM to | Property Type | Property Name | Description | | :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SimpleRelation | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/relations/srv_dns_relation.md b/docs/open_asset_model/relations/srv_dns_relation.md index 3bff5eb..cbff3ec 100644 --- a/docs/open_asset_model/relations/srv_dns_relation.md +++ b/docs/open_asset_model/relations/srv_dns_relation.md @@ -32,3 +32,7 @@ In summary, `SRVDNSRelation` brings full support for SRV record semantics into t | Property Type | Property Name | Description | | :-----------------: | :-----------------: | :------------ | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this SRVDNSRelation | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file From cba30c18ed3d8f61bedfe2660edd7087cdc53636 Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 8 Jul 2025 01:31:41 -0400 Subject: [PATCH 25/45] initial commit --- docs/open_asset_model/assets/location.md | 56 +++++++++++++++++++ docs/open_asset_model/assets/phone.md | 56 +++++++++++++++++++ .../assets/product_release.md | 53 ++++++++++++++++++ 3 files changed, 165 insertions(+) create mode 100644 docs/open_asset_model/assets/location.md create mode 100644 docs/open_asset_model/assets/phone.md create mode 100644 docs/open_asset_model/assets/product_release.md diff --git a/docs/open_asset_model/assets/location.md b/docs/open_asset_model/assets/location.md new file mode 100644 index 0000000..5bfb2bf --- /dev/null +++ b/docs/open_asset_model/assets/location.md @@ -0,0 +1,56 @@ +# :simple-owasp: Location + +The **Location** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a physical, postal, or geo-administrative address where an entity, asset, or infrastructure component is situated. Modeling locations is essential for *physical security*, *compliance*, and *geo-contextual threat intelligence*. + +* **Definition:** A `Location` asset encapsulates structured geographic and civic data elements such as street name, building number, city, province, country, and more. It is designed to express physical placement or registration information for various assets in the OAM. + +* **Purpose:** By defining `Location` as a core asset, the model enables linkage between digital infrastructure and their physical contexts. This supports use cases like data residency enforcement, regional exposure analysis, and logistics around physical components of an attack surface. + +* **Design Choice:** Each attribute within the `Location` asset is modeled with optionality in mind, allowing broad applicability — from a complete civic address to partial location data such as city-only or PO Box information. The inclusion of a `GLN` (Global Location Number) field aligns with standardized supply chain and logistics frameworks. + +In summary, the `Location` asset type serves as a structured and flexible mechanism for tying assets to their real-world geographic presence — aiding in operational awareness, compliance mapping, and geospatial intelligence. + +## :material-map-marker: Location Attributes + +| Attributes | Type | Required | Description | +| :---------------: | :----: | :-----------------------: | :----------------------------------------------------- | +| `address` | string | :material-check-decagram: | Full unstructured address (fallback or human-readable) | +| `building` | string | :material-checkbox-blank-circle-outline: | Building name or identifier | +| `building_number` | string | :material-checkbox-blank-circle-outline: | Street number of the building | +| `street_name` | string | :material-checkbox-blank-circle-outline: | Name of the street | +| `unit` | string | :material-checkbox-blank-circle-outline: | Apartment, suite, or unit number | +| `po_box` | string | :material-checkbox-blank-circle-outline: | Post office box number | +| `city` | string | :material-check-decagram: | City or municipality name | +| `locality` | string | :material-checkbox-blank-circle-outline: | District, borough, or neighborhood name | +| `province` | string | :material-checkbox-blank-circle-outline: | State, province, or administrative div | +| `country` | string | :material-checkbox-blank-circle-outline: | Country name (ISO recommended) | +| `postal_code` | string | :material-checkbox-blank-circle-outline: | ZIP or postal code | +| `gln` | int | :material-checkbox-blank-circle-outline: | Global Location Number (GS1 standard) | + +## :material-map-marker: Location Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Location | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Location | + +## :material-map-marker: Location Outgoing Relations + +```mermaid +graph TD +loc["Location (e.g. Frankfurt)"] +ident["Identifier (e.g. AWS Data Center)"] +rel@{ shape: braces, label: "id" } +loc --o rel +rel --> ident +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the `Location` alternative IDs, such as facility names | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/phone.md b/docs/open_asset_model/assets/phone.md new file mode 100644 index 0000000..b1862a0 --- /dev/null +++ b/docs/open_asset_model/assets/phone.md @@ -0,0 +1,56 @@ +# :simple-owasp: Phone + +The **Phone** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a structured phone number associated with a person, organization, or service. This includes landlines, mobile phones, and fax numbers, supporting international formats and extensions. + +* **Definition:** A `Phone` asset includes raw and standardized (E.164) representations of phone numbers, along with metadata such as type (e.g., mobile or fax), country code, and optional extension. + +* **Purpose:** Phone numbers are valuable in *OSINT investigations*, *phishing detection*, *social engineering risk analysis*, and mapping *communications infrastructure*. Modeling them as first-class assets allows for clear linkage to entities and tracing how they appear across datasets. + +* **Design Choice:** The model uses the E.164 international standard to normalize phone numbers for global consistency. A `Type` field supports differentiation between regular, mobile, and fax numbers, enabling more nuanced analysis and relation modeling. + +In summary, the `Phone` asset type brings structure and semantic clarity to phone number data, providing essential context for investigative and security workflows in the OAM. + +## :material-phone: Phone Attributes + +| Attributes | Type | Required | Description | +| :--------------: | :----: | :-----------------------: | :--------------------------------------------------- | +| `type` | string | :material-checkbox-blank-circle-outline: | Type of phone number — `phone`, `fax`, or `mobile` | +| `raw` | string | :material-check-decagram: | Original, unprocessed string version of the number | +| `e164` | string | :material-check-decagram: | Standardized E.164 format (e.g., `+14155552671`) | +| `country_abbrev` | string | :material-checkbox-blank-circle-outline: | ISO 3166-1 alpha-2 country abbreviation (e.g., `US`) | +| `country_code` | int | :material-checkbox-blank-circle-outline: | Country dialing code (e.g., `1` for the US) | +| `ext` | string | :material-checkbox-blank-circle-outline: | Phone extension, if applicable (e.g., `x1234`) | + +## :material-phone: Phone Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Phone | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Phone | + +## :material-phone: Phone Outgoing Relations + +```mermaid +graph TD +phone["Phone (+1-415-555-2671)"] +acct["Account"] +account@{ shape: braces, label: "account" } +phone --o account +account --> acct + +contactrec["ContactRecord"] +contact@{ shape: braces, label: "contact" } +phone --o contact +contact --> contactrec +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `account` | [`Account`](./account.md) | Links the `Phone` number to a customer account | +| [`SimpleRelation`](../relations/simple_relation.md) | `contact` | [`ContactRecord`](./contact_record.md) | Links the `Phone` number to additional customer information | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file diff --git a/docs/open_asset_model/assets/product_release.md b/docs/open_asset_model/assets/product_release.md new file mode 100644 index 0000000..5f6bdc7 --- /dev/null +++ b/docs/open_asset_model/assets/product_release.md @@ -0,0 +1,53 @@ +# :simple-owasp: ProductRelease + +The **ProductRelease** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a specific version or release milestone of a technology product. This asset enables security analysts to track when a product version was introduced, helping to contextualize vulnerabilities, lifecycles, and compatibility considerations. + +* **Definition:** A `ProductRelease` asset identifies a named version or release of a product (e.g., "v2.4.1", "2023 Q1 Patch"). It may optionally include the release date in a standardized format. + +* **Purpose:** Tracking product releases is vital for assessing *vulnerability exposure*, *patch levels*, *software supply chain integrity*, and *asset compatibility*. This asset type supports fine-grained analysis of software deployment across environments. + +* **Design Choice:** By separating a `ProductRelease` from the broader `Product` asset, the model supports a clean versioning structure that can evolve independently. This separation enables better temporal modeling and historical tracking of asset deployments and vulnerabilities. + +In summary, the `ProductRelease` asset type provides version-level granularity for representing software and hardware products, enriching the asset graph for supply chain and lifecycle analysis. + +## :material-package-variant: ProductRelease Attributes + +| Attributes | Type | Required | Description | +| :------------: | :----: | :-----------------------: | :-------------------------------------------------------- | +| `name` | string | :material-check-decagram: | Identifier of the release (e.g., `v1.2.3`, `2024.06`) | +| `release_date` | string | :material-checkbox-blank-circle-outline: | Optional date the release became available (`YYYY-MM-DD`) | + +## :material-package-variant: ProductRelease Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this ProductRelease | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this ProductRelease | +| [`VulnProperty`](../properties/vuln_property.md) | Vulnerability ID | Specifies a vulnerability associated with this ProductRelease | + +## :material-package-variant: ProductRelease Outgoing Relations + +```mermaid +graph TD +release["ProductRelease (Apache HTTP Server v1.2.3)"] +ident["Identifier"] +rel@{ shape: braces, label: "id" } +release --o rel +rel --> ident + +url["URL"] +urlRel@{ shape: braces, label: "website" } +release --o urlRel +urlRel --> url +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the `ProductRelease` to other identifiers, such as a serial number | +| [`SimpleRelation`](../relations/simple_relation.md) | `website` | [`URL`](./url.md) | Links the `ProductRelease` to a website with additional information | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file From c73a1baf67e20c079c0a44be8e5d3b87afaeb9ac Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 8 Jul 2025 21:10:37 -0400 Subject: [PATCH 26/45] initial commit --- docs/open_asset_model/assets/autnum_record.md | 70 +++++++++++++++++ docs/open_asset_model/assets/ipnet_record.md | 76 +++++++++++++++++++ docs/open_asset_model/assets/service.md | 71 +++++++++++++++++ 3 files changed, 217 insertions(+) create mode 100644 docs/open_asset_model/assets/autnum_record.md create mode 100644 docs/open_asset_model/assets/ipnet_record.md create mode 100644 docs/open_asset_model/assets/service.md diff --git a/docs/open_asset_model/assets/autnum_record.md b/docs/open_asset_model/assets/autnum_record.md new file mode 100644 index 0000000..124d900 --- /dev/null +++ b/docs/open_asset_model/assets/autnum_record.md @@ -0,0 +1,70 @@ +# :simple-owasp: AutnumRecord + +The **AutnumRecord** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents authoritative **registration data** for an Autonomous System (AS), as provided by Regional Internet Registries (RIRs) via RDAP or legacy WHOIS. This includes ownership and operational metadata related to an **Autonomous System Number (ASN)**—the numeric identifier used in BGP routing. + +- **Definition:** An `AutnumRecord` contains parsed RDAP registration data about an ASN, including its number, handle, registered name, lifecycle dates, and optional status flags. It also includes the raw source text for auditing or secondary parsing. + +- **Purpose:** Modeling AS registration data as a distinct asset allows analysts to pivot from infrastructure to **attribution**, understand who controls internet routing authority, and detect AS-level behavior changes (e.g., hijacks, acquisitions, multi-homing). It supports graph queries like “which ASNs are linked to a given organization?” or “what netblocks does a registered AS announce?” + +- **Design Choice:** Like `DomainRecord`, the `AutnumRecord` includes both structured and unstructured fields, preserving original RDAP/WHOIS responses while enabling consistent graph modeling. Fields are optimized for operational monitoring and attribution while remaining tolerant to registry variability. + +The AutnumRecord asset type enables attribution, tracking, and auditing of ASNs across the global routing system, serving as a critical bridge between technical infrastructure and organizational ownership. + +## :material-file-cabinet: AutnumRecord Attributes + +| Attributes | Type | Required | Description | +|:----------------:|:-----------------:|:--------:|:------------| +| `number` | integer | :material-check-decagram: | Autonomous System Number (ASN) | +| `handle` | string | :material-check-decagram: | Registry-specific handle (e.g., `AS15169`) | +| `name` | string | :material-check-decagram: | Name of the AS as registered (e.g., `GOOGLE`) | +| `created_date` | string (ISO date) | :material-check-decagram: | Date the ASN was first registered | +| `updated_date` | string (ISO date) | :material-check-decagram: | Last modification date of the registration | +| `status` | array of strings | :material-checkbox-blank-circle-outline: | Optional status flags | +| `whois_server` | string | :material-checkbox-blank-circle-outline: | RDAP/WHOIS server that served the registration data | +| `raw` | string | :material-checkbox-blank-circle-outline: | Original registration record text or RDAP JSON | + +## :material-file-cabinet: AutnumRecord Properties + +| Property Type | Property Name | Description | +|:-------------:|:-------------:|:------------| +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Timestamp of the last time this record was updated or verified | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates which data source retrieved the registration | + +## :material-file-cabinet: AutnumRecord Outgoing Relations + +```mermaid +graph TD +autrec["AutnumRecord"] +whois["FQDN"] +whoisRel@{ shape: braces, label: "whois_server" } +autrec --o whoisRel +whoisRel --> whois + +contact["ContactRecord"] +contactrel@{ shape: braces, label: "registrant +admin_contact +abuse_contact +technical_contact" } +autrec --o contactrel +contactrel --> contact + +url["URL"] +urlRel@{ shape: braces, label: "rdap_url" } +autrec --o urlRel +urlRel --> url +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `whois_server` | [`FQDN`](./fqdn.md) | Links the ASN registration information with the correct WHOIS server | +| [`SimpleRelation`](../relations/simple_relation.md) | `registrant` | [`ContactRecord`](./contact_record.md) | Links the ASN registration information with registrant contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `admin_contact` | [`ContactRecord`](./contact_record.md) | Links the ASN registration information with admin contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `abuse_contact` | [`ContactRecord`](./contact_record.md) | Links the ASN registration information with contact information for abuse reporting | +| [`SimpleRelation`](../relations/simple_relation.md) | `technical_contact` | [`ContactRecord`](./contact_record.md) | Links the ASN registration information with contact information of technical personnel | +| [`SimpleRelation`](../relations/simple_relation.md) | `rdap_url` | [`URL`](./url.md) | Links the ASN registration information to its associated web page | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/ipnet_record.md b/docs/open_asset_model/assets/ipnet_record.md new file mode 100644 index 0000000..4b9ab77 --- /dev/null +++ b/docs/open_asset_model/assets/ipnet_record.md @@ -0,0 +1,76 @@ +# :simple-owasp: IPNetRecord + +The **IPNetRecord** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents authoritative **registration data** for a block of IP addresses (IPv4 or IPv6), typically retrieved from a Regional Internet Registry (RIR) via the [RDAP](https://www.arin.net/resources/registry/whois/rdap/) protocol. This record captures the ownership, administrative, and organizational context of a given CIDR allocation. + +- **Definition:** An `IPNetRecord` models a registered IP network block with accompanying metadata such as handle, range, status, country, and registration dates. It mirrors RDAP responses from RIRs like ARIN, RIPE, APNIC, AFRINIC, and LACNIC. + +- **Purpose:** By modeling IP allocations as assets, `IPNetRecord` entries allow external infrastructure to be tied back to real-world entities. This is essential for **attribution**, **provider relationships**, and **BGP analysis**. It enables analysts to query: “Who owns this IP range?”, “What organization controls this infrastructure?”, or “Which AS announces this block?” + +- **Design Choice:** The `IPNetRecord` structure preserves key fields from RDAP while ensuring they are queryable in graph form. CIDR blocks are expressed as typed network prefixes with explicit start and end addresses. Optional fields provide additional semantics for routing origin, delegation hierarchy, and jurisdictional scope. + +The IPNetRecord asset enables infrastructure attribution, jurisdictional mapping, and inter-provider analysis within the OAM graph, anchoring raw IPs and services in a meaningful real-world context. + +## :material-file-cabinet: IPNetRecord Attributes + +| Attributes | Type | Required | Description | +|:-----------------:|:--------------:|:--------:|:------------| +| `cidr` | CIDR prefix | :material-check-decagram: | The registered network range in CIDR notation (e.g., `192.0.2.0/24`) | +| `handle` | string | :material-check-decagram: | RIR-assigned handle for the record | +| `name` | string | :material-check-decagram: | Name associated with the registration (e.g., organization or role) | +| `type` | string | :material-check-decagram: | Type of allocation (e.g., `ALLOCATED`, `ASSIGNED`) | +| `start_address` | IP address | :material-check-decagram: | First IP in the range | +| `end_address` | IP address | :material-check-decagram: | Last IP in the range | +| `created_date` | string (ISO) | :material-check-decagram: | Date the block was initially registered | +| `updated_date` | string (ISO) | :material-check-decagram: | Most recent modification date | +| `status` | array of strings | :material-checkbox-blank-circle-outline: | Optional flags such as `active`, `allocated`, `legacy` | +| `whois_server` | string | :material-checkbox-blank-circle-outline: | RIR WHOIS or RDAP server used to retrieve the data | +| `method` | string | :material-checkbox-blank-circle-outline: | Discovery method (e.g., `RDAP`, `WHOIS`) | +| `country` | string (ISO) | :material-checkbox-blank-circle-outline: | Country code associated with the allocation (e.g., `US`) | +| `parent_handle` | string | :material-checkbox-blank-circle-outline: | Handle of the parent allocation, if applicable | +| `raw` | string | :material-checkbox-blank-circle-outline: | Raw RDAP or WHOIS response preserved for auditing | + +## :material-file-cabinet: IPNetRecord Properties + +| Property Type | Property Name | Description | +|:-------------:|:-------------:|:------------| +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Timestamp of the last time this record was updated or verified | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates which data source retrieved the registration | + +## :material-file-cabinet: IPNetRecord Outgoing Relations + +```mermaid +graph TD +iprec["IPNetRecord (192.0.2.0/24)"] +whois["FQDN"] +whoisRel@{ shape: braces, label: "whois_server" } +iprec --o whoisRel +whoisRel --> whois + +contact["ContactRecord"] +contactrel@{ shape: braces, label: "registrant +admin_contact +abuse_contact +technical_contact" } +iprec --o contactrel +contactrel --> contact + +url["URL"] +urlRel@{ shape: braces, label: "rdap_url" } +iprec --o urlRel +urlRel --> url +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `whois_server` | [`FQDN`](./fqdn.md) | Links the netblock registration information with the correct WHOIS server | +| [`SimpleRelation`](../relations/simple_relation.md) | `registrant` | [`ContactRecord`](./contact_record.md) | Links the netblock registration information with registrant contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `admin_contact` | [`ContactRecord`](./contact_record.md) | Links the netblock registration information with admin contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `abuse_contact` | [`ContactRecord`](./contact_record.md) | Links the netblock registration information with contact information for abuse reporting | +| [`SimpleRelation`](../relations/simple_relation.md) | `technical_contact` | [`ContactRecord`](./contact_record.md) | Links the netblock registration information with contact information of technical personnel | +| [`SimpleRelation`](../relations/simple_relation.md) | `rdap_url` | [`URL`](./url.md) | Links the netblock registration information to its associated web page | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/service.md b/docs/open_asset_model/assets/service.md new file mode 100644 index 0000000..fd09e16 --- /dev/null +++ b/docs/open_asset_model/assets/service.md @@ -0,0 +1,71 @@ +# :simple-owasp: Service + +The **Service** asset type in the [OWASP](https://owasp.org) [Open Asset Model](https://github.com/owasp-amass/open-asset-model) (OAM) represents a **network-accessible service** discovered during external intelligence collection. This typically includes any server process that responded to a connection attempt on a known port—such as web servers, SSH daemons, mail servers, database listeners, and more. + +- **Definition:** A `Service` asset captures metadata about a responding network service, including its type (e.g., `http`, `ssh`, `ftp`), the raw output from its initial response, and optionally a set of key-value `attributes` such as HTTP headers or protocol banners. + +- **Purpose:** The `Service` asset allows the model to **anchor discovery events at the protocol layer**, enabling linkage between hosts (e.g., IP addresses or FQDNs), ports, and deeper contextual assets like `TLSCertificate` or `Product`. This supports questions like: “What is responding on port 443?”, “Which certificates are served from this endpoint?”, or “What headers are exposed by this HTTP server?” + +- **Design Choice:** By treating services as first-class assets, OAM avoids overloading lower-level host or transport layers with application-layer metadata. This cleanly separates service-level observations and makes it easy to enrich, correlate, or reason over what’s actually deployed on a given interface. + +The Service asset type anchors application-layer discovery to observable ports on internet-facing hosts, enabling technology fingerprinting, encryption analysis, and vulnerability enrichment across the OAM graph. + +## :material-server-network: Service Attributes + +| Attributes | Type | Required | Description | +|:-----------------:|:-----------:|:--------:|:------------| +| `unique_id` | string | :material-check-decagram: | Unique identifier for the service | +| `service_type` | string | :material-check-decagram: | Protocol or service label (e.g., `http`, `ssh`, `smtp`) | +| `output` | string | :material-checkbox-blank-circle-outline: | Raw response received from the service (e.g., HTTP banner, SSH version) | +| `output_length` | integer | :material-checkbox-blank-circle-outline: | Length of the captured `output` string | +| `attributes` | object | :material-checkbox-blank-circle-outline: | Key-value pairs extracted from the service response (e.g., headers, options) | + +## :material-server-network: Service Properties + +| Property Type | Property Name | Description | +| :-----------------: | :-----------------: | :------------ | +| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Service | +| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Service | + +## :material-server-network: Service Outgoing Relations + +```mermaid +graph TD +service["Service"] +org["Organization"] +provider@{ shape: braces, label: "provider" } +service --o provider +provider --> org + +cert["TLSCertificate"] +certificate@{ shape: braces, label: "certificate" } +service --o certificate +certificate --> cert + +file["File"] +url["URL"] +tos@{ shape: braces, label: "terms_of_service" } +service --o tos +tos --> file +tos --> url + +prod["Product"] +prodrel["ProductRelease"] +used@{ shape: braces, label: "product_used" } +service --o used +used --> prod +used --> prodrel +``` + +--- + +| Relation Type | Relation Label | Target Assets | Description | +| :-----------------: | :----------------: | :--------------: | :------------ | +| [`SimpleRelation`](../relations/simple_relation.md) | `provider` | [`Organization`](./organization.md) | Links the service with the `Organization` hosting the server | +| [`SimpleRelation`](../relations/simple_relation.md) | `certificate` | [`TLSCertificate`](./tls_certificate.md) | Links the service with an associated TLS certificate | +| [`SimpleRelation`](../relations/simple_relation.md) | `terms_of_service` | [`File`](./file.md), [`URL`](./url.md) | Links the service with terms of service information | +| [`SimpleRelation`](../relations/simple_relation.md) | `product_used` | [`Product`](./product.md), [`ProductRelease`](./product_release.md) | Links the service to `Product` and versioning details | + +--- + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* From 9ad668af5eb045750cb645c2716db3b0d8b3f3f8 Mon Sep 17 00:00:00 2001 From: caffix Date: Tue, 8 Jul 2025 21:10:51 -0400 Subject: [PATCH 27/45] updates --- docs/open_asset_model/assets/account.md | 14 +++++++------ .../assets/autonomous_system.md | 2 +- .../open_asset_model/assets/contact_record.md | 14 ++++++------- docs/open_asset_model/assets/domain_record.md | 10 ++++++---- docs/open_asset_model/assets/file.md | 4 ++-- docs/open_asset_model/assets/fqdn.md | 2 +- .../open_asset_model/assets/funds_transfer.md | 12 ++++++----- docs/open_asset_model/assets/identifier.md | 2 +- docs/open_asset_model/assets/ip_address.md | 2 +- docs/open_asset_model/assets/location.md | 2 +- docs/open_asset_model/assets/netblock.md | 2 +- docs/open_asset_model/assets/organization.md | 2 +- docs/open_asset_model/assets/person.md | 12 ++++++----- docs/open_asset_model/assets/phone.md | 2 +- docs/open_asset_model/assets/product.md | 20 ++++++++++--------- .../assets/product_release.md | 2 +- .../assets/tls_certificate.md | 2 +- docs/open_asset_model/assets/url.md | 2 +- docs/open_asset_model/index.md | 20 ------------------- .../properties/dns_property.md | 2 +- docs/open_asset_model/properties/index.md | 2 +- .../properties/simple_property.md | 2 +- .../properties/source_property.md | 2 +- .../properties/vuln_property.md | 2 +- .../relations/basic_dns_relation.md | 2 +- docs/open_asset_model/relations/index.md | 2 +- .../relations/port_relation.md | 2 +- .../relations/pref_dns_relation.md | 2 +- .../relations/simple_relation.md | 2 +- .../relations/srv_dns_relation.md | 2 +- mkdocs.yml | 6 ++++++ 31 files changed, 76 insertions(+), 80 deletions(-) diff --git a/docs/open_asset_model/assets/account.md b/docs/open_asset_model/assets/account.md index bf1ee8c..f4c00ee 100644 --- a/docs/open_asset_model/assets/account.md +++ b/docs/open_asset_model/assets/account.md @@ -38,10 +38,12 @@ Modeling accounts as first-class assets enables reasoning about identity exposur Account assets can be linked to services, users, or organizations through relations, enabling workflows such as credential exposure detection, service-to-user mapping, or analysis of abandoned or inactive accounts across cloud providers or infrastructure environments. +Accounts are identity-centric primitives that enrich the graph’s ability to reason about control, access, and exposure across digital systems. + ## :material-account: Account Attributes -| Attributes | Type | Required. | Description. | -| :-------------------: | :---------: | :----------: | :------------- | +| Attributes | Type | Required | Description | +| :-------------------: | :---------: | :---------: | :------------ | | `unique_id` | string | :material-check-decagram: | Unique identifier for the account within the model | | `account_type` | string | :material-check-decagram: | Classification of the account (e.g., `cloud`, `bank`, `user`) | | `username` | string | :material-checkbox-blank-circle-outline: | Login name, email, or screen name associated with the account | @@ -62,16 +64,16 @@ Account assets can be linked to services, users, or organizations through relati graph TD acct["Account"] ident["Identifier"] -idRel@{ shape: braces, label: "id"} +idRel@{ shape: braces, label: "id" } acct --o idRel idRel --> ident org["Organization"] person["Person] -user@{ shape: braces, label: "user"} +user@{ shape: braces, label: "user" } acct --o user user --> org -user --> persom +user --> person ``` --- @@ -83,4 +85,4 @@ user --> persom --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/autonomous_system.md b/docs/open_asset_model/assets/autonomous_system.md index 3cea87d..3208c8a 100644 --- a/docs/open_asset_model/assets/autonomous_system.md +++ b/docs/open_asset_model/assets/autonomous_system.md @@ -48,4 +48,4 @@ regrel --> autnum --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/contact_record.md b/docs/open_asset_model/assets/contact_record.md index 8cf68e3..f15fb77 100644 --- a/docs/open_asset_model/assets/contact_record.md +++ b/docs/open_asset_model/assets/contact_record.md @@ -56,13 +56,13 @@ simple6 --> url | Relation Type | Relation Label | Target Assets | Description | | :-----------------: | :----------------: | :--------------: | :------------ | -| [`SimpleRelation`](../relations/simple_relation.md) | `fqdn` | [`FQDN`](#fqdn) | Represents a FQDN discovered in the contact information | -| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](#identifer) | Represents an ID (e.g. email address) in the contact information | -| [`SimpleRelation`](../relations/simple_relation.md) | `organization` | [`Organization`](#organization) | Represents an organization name in the contact information | -| [`SimpleRelation`](../relations/simple_relation.md) | `person` | [`Person`](#person) | Represents a person's name discovered with the contact information | -| [`SimpleRelation`](../relations/simple_relation.md) | `phone` | [`Phone`](#phone) | Represents a phone number in the contact information | -| [`SimpleRelation`](../relations/simple_relation.md) | `url` | [`URL`](#url) | Represents an URL discovered in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `fqdn` | [`FQDN`](./fqdn.md) | Represents a FQDN discovered in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Represents an ID (e.g. email address) in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `organization` | [`Organization`](./organization.md) | Represents an organization name in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `person` | [`Person`](./person) | Represents a person's name discovered with the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `phone` | [`Phone`](./phone.md) | Represents a phone number in the contact information | +| [`SimpleRelation`](../relations/simple_relation.md) | `url` | [`URL`](./url.md) | Represents an URL discovered in the contact information | --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/domain_record.md b/docs/open_asset_model/assets/domain_record.md index 62f17ac..9db8252 100644 --- a/docs/open_asset_model/assets/domain_record.md +++ b/docs/open_asset_model/assets/domain_record.md @@ -8,7 +8,9 @@ The **DomainRecord** asset type in the [OWASP](https://owasp.org) [Open Asset Mo - **Design Choice:** Keeping both *normalised* fields (e.g., `created_date`) **and** the original `raw` text preserves machine‑readable consistency while ensuring full auditability. Optional fields make the structure tolerant of incomplete WHOIS responses, and the `status` array supports the many ICANN/ccTLD state strings without schema changes. -## :material-dns: DomainRecord Attributes +DomainRecords provide authoritative visibility into how domain names are registered, updated, and governed, making them critical for attribution, expiration monitoring, and organizational mapping within the external asset graph. + +## :material-file-cabinet: DomainRecord Attributes | Attributes | Type | Required | Description | | :---------------: | :-----------------: | :------: | :---------- | @@ -25,14 +27,14 @@ The **DomainRecord** asset type in the [OWASP](https://owasp.org) [Open Asset Mo | `raw` | string | :material-checkbox-blank-circle-outline: | Unparsed WHOIS / RDAP text for auditing | | `id` | string | :material-checkbox-blank-circle-outline: | Optional registry‑specific object ID | -## :material-dns: DomainRecord Properties +## :material-file-cabinet: DomainRecord Properties | Property Type | Property Name | Description | | :-----------: | :-----------: | :---------- | | [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Timestamp of the most recent WHOIS/RDAP pull | | [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Identifies which discovery module produced the record | -## :material-dns: DomainRecord Outgoing Relations +## :material-file-cabinet: DomainRecord Outgoing Relations ```mermaid graph TD @@ -67,4 +69,4 @@ contactrel --> contact --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/file.md b/docs/open_asset_model/assets/file.md index db040b7..f1d9a5d 100644 --- a/docs/open_asset_model/assets/file.md +++ b/docs/open_asset_model/assets/file.md @@ -34,7 +34,7 @@ file --o urlRel urlRel --> url contactrec["ContactRecord"] -contains@{ shape: braces; label: "contains" } +contains@{ shape: braces, label: "contains" } file --o contains contains --> contactrec contains --> url @@ -49,4 +49,4 @@ contains --> url --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index 0ac1f1e..d1eb437 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -76,4 +76,4 @@ regrel --> domrec --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/funds_transfer.md b/docs/open_asset_model/assets/funds_transfer.md index 298af50..17ef80b 100644 --- a/docs/open_asset_model/assets/funds_transfer.md +++ b/docs/open_asset_model/assets/funds_transfer.md @@ -8,6 +8,8 @@ The **FundsTransfer** asset type in the [OWASP](https://owasp.org) [Open Asset M - **Design Choice:** This type focuses on capturing the *structure* of a transfer (e.g., amount, method, and timing) rather than sensitive or regulated content (like full account numbers). Optional fields like `exchange_rate` allow the model to support cross-currency scenarios and future integration with financial intelligence tooling, while keeping the core schema minimal and auditable. +The FundsTransfer asset type enables graph-based tracking of financial transactions, providing insight into economic behavior, potential fraud, or organizational connections in the external attack surface. + ## :material-cash-multiple: FundsTransfer Attributes | Attributes | Type | Required | Description | @@ -33,22 +35,22 @@ The **FundsTransfer** asset type in the [OWASP](https://owasp.org) [Open Asset M graph TD transfer["FundsTransfer ($5,000 USD)"] ident["Identifer"] -idRel@{ shape, braces; label: "id" } +idRel@{ shape, braces, label: "id" } transfer --o idRel idRel --> ident acct1["Account (acct-123)"] -fromRel@{ shape: braces; label: "sender" } +fromRel@{ shape: braces, label: "sender" } transfer --o fromRel fromRel --> acct1 acct2["Account (acct-456)"] -toRel@{ shape: braces; label: "recipient" } +toRel@{ shape: braces, label: "recipient" } transfer --o toRel toRel --> acct2 org["Organization"] -third@{ shape: braces; label: "third_party" } +third@{ shape: braces, label: "third_party" } transfer --o third third --> org ``` @@ -64,4 +66,4 @@ third --> org --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/identifier.md b/docs/open_asset_model/assets/identifier.md index cf6e42e..a869ddc 100644 --- a/docs/open_asset_model/assets/identifier.md +++ b/docs/open_asset_model/assets/identifier.md @@ -59,4 +59,4 @@ allrel --> contact --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/ip_address.md b/docs/open_asset_model/assets/ip_address.md index 17ad781..0037de0 100644 --- a/docs/open_asset_model/assets/ip_address.md +++ b/docs/open_asset_model/assets/ip_address.md @@ -51,4 +51,4 @@ port --> service --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/location.md b/docs/open_asset_model/assets/location.md index 5bfb2bf..213b315 100644 --- a/docs/open_asset_model/assets/location.md +++ b/docs/open_asset_model/assets/location.md @@ -53,4 +53,4 @@ rel --> ident --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/netblock.md b/docs/open_asset_model/assets/netblock.md index 83df138..1c80cc3 100644 --- a/docs/open_asset_model/assets/netblock.md +++ b/docs/open_asset_model/assets/netblock.md @@ -49,4 +49,4 @@ regrel --> iprec --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/organization.md b/docs/open_asset_model/assets/organization.md index 34f0536..c72e400 100644 --- a/docs/open_asset_model/assets/organization.md +++ b/docs/open_asset_model/assets/organization.md @@ -106,4 +106,4 @@ funding --> person --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/person.md b/docs/open_asset_model/assets/person.md index 7ef1e01..b82ab2a 100644 --- a/docs/open_asset_model/assets/person.md +++ b/docs/open_asset_model/assets/person.md @@ -8,6 +8,8 @@ The **Person** asset type in the [OWASP](https://owasp.org) [Open Asset Model](h - **Design Choice:** The `Person` structure includes multiple levels of name granularity to enable flexible matching and entity resolution. Optional fields (e.g., `birth_date`, `gender`) support deeper analysis when present, but are not required—ensuring compatibility with incomplete or privacy-preserving sources. The model avoids sensitive personal information (e.g., national IDs) unless already exposed via legitimate public data sources. +The Person asset type enables entity-centric analysis within the Open Asset Model, helping analysts reason about attribution, ownership, and relationships between human actors and the infrastructure they operate or influence. + ## :material-account: Person Attributes | Attributes | Type | Required | Description | @@ -33,22 +35,22 @@ The **Person** asset type in the [OWASP](https://owasp.org) [Open Asset Model](h graph TD person["Person (Jane E. Smith)"] ident["Identifier"] -idRel@{ shape: braces; label: "id" } +idRel@{ shape: braces, label: "id" } person --o idRel idRel --> ident loc["Location (Street Address)"] -locRel@{ shape: braces; label: "address" } +locRel@{ shape: braces, label: "address" } person --o locRel locRel --> loc phone["Phone"] -phoneRel@{ shape: braces; label: "phone" } +phoneRel@{ shape: braces, label: "phone" } person --o phoneRel phoneRel --> phone acct["Account"] -account@{ shape: braces; label: "account" } +account@{ shape: braces, label: "account" } person --o account account --> acct ``` @@ -64,4 +66,4 @@ account --> acct --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/phone.md b/docs/open_asset_model/assets/phone.md index b1862a0..db34519 100644 --- a/docs/open_asset_model/assets/phone.md +++ b/docs/open_asset_model/assets/phone.md @@ -53,4 +53,4 @@ contact --> contactrec --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/product.md b/docs/open_asset_model/assets/product.md index a31bb11..e617134 100644 --- a/docs/open_asset_model/assets/product.md +++ b/docs/open_asset_model/assets/product.md @@ -8,6 +8,8 @@ The **Product** asset type in the [OWASP](https://owasp.org) [Open Asset Model]( - **Design Choice:** The `Product` structure is intentionally minimal to support broad applicability. While the `ProductRelease` handles additional information such as version, vendor, and licensing via `Identifier` assets and properties, the core type emphasizes identification and categorization. The inclusion of `country_of_origin` supports use cases related to supply chain risk and regulatory compliance. +The Product asset type provides structured visibility into the technologies exposed in an organization's external footprint, supporting vulnerability mapping, software inventory, and strategic technology analysis. + ## :material-package-variant: Product Attributes | Attributes | Type | Required | Description | @@ -32,24 +34,24 @@ The **Product** asset type in the [OWASP](https://owasp.org) [Open Asset Model]( graph TD product["Product (nginx)"] ident["Identifier"] -idRel@{ shape: braces; label: "id" } +idRel@{ shape: braces, label: "id" } product --o idRel idRel --> ident org["Organization"] -vendorRel@{ shape: braces; label: "manufacturer" } +vendorRel@{ shape: braces, label: "manufacturer" } product --o vendorRel vendorRel --> org url["URL"] -website@{ shape: braces; label: "website" } -product --o website -website --> url +webRel@{ shape: braces, label: "website" } +product --o webRel +webRel --> url prodrel["ProductRelease"] -release@{ shape: braces; label: "release" } -product --o release -release --> prodrel +rel@{ shape: braces, label: "release" } +product --o rel +rel --> prodrel ``` --- @@ -63,4 +65,4 @@ release --> prodrel --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/product_release.md b/docs/open_asset_model/assets/product_release.md index 5f6bdc7..847e70f 100644 --- a/docs/open_asset_model/assets/product_release.md +++ b/docs/open_asset_model/assets/product_release.md @@ -50,4 +50,4 @@ urlRel --> url --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/tls_certificate.md b/docs/open_asset_model/assets/tls_certificate.md index 0541f23..70ef72c 100644 --- a/docs/open_asset_model/assets/tls_certificate.md +++ b/docs/open_asset_model/assets/tls_certificate.md @@ -103,4 +103,4 @@ issuer --> cert --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/assets/url.md b/docs/open_asset_model/assets/url.md index dae5d92..1a8b5aa 100644 --- a/docs/open_asset_model/assets/url.md +++ b/docs/open_asset_model/assets/url.md @@ -78,4 +78,4 @@ filerel --> file --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/index.md b/docs/open_asset_model/index.md index 4457c39..925786e 100644 --- a/docs/open_asset_model/index.md +++ b/docs/open_asset_model/index.md @@ -14,15 +14,12 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a --- - ## :material-graph: Explore OAM Asset Types --- -
- - :material-file-account:{ .lg .middle } __Account__ --- @@ -31,18 +28,14 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/account/) - - :material-registered-trademark:{ .lg .middle } __Domain Record__ --- - Gather domain insights, including Whois and registrar details [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/domain_record/) - - - :material-comment-outline:{ .lg .middle } __Contact Record__ --- @@ -51,7 +44,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/contact_record/) - - :material-dns:{ .lg .middle } __FQDN__ --- @@ -60,7 +52,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/fqdn/) - - :material-file-find:{ .lg .middle } __File__ --- @@ -69,7 +60,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/file/) - - :material-bank:{ .lg .middle } __Funds Transfer__ --- @@ -78,7 +68,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/funds_transfer/) - - :material-id-card:{ .lg .middle } __Identifier__ --- @@ -87,7 +76,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/identifier/) - - :material-router:{ .lg .middle } __IP Address__ --- @@ -96,7 +84,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/ip_address/) - - :material-office-building-marker:{ .lg .middle } __Organization__ --- @@ -105,7 +92,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/organization/) - - :material-account-outline:{ .lg .middle } __Person__ --- @@ -114,8 +100,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/person/) - - - :material-apps:{ .lg .middle } __Product__ --- @@ -124,8 +108,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/product/) - - - :material-file-certificate-outline:{ .lg .middle } __TLS Certificate__ --- @@ -134,8 +116,6 @@ The **Amass Project's** [Open Asset Model](https://github.com/owasp-amass/open-a [:octicons-arrow-right-24: Learn more](https://owasp-amass.github.io/docs/open-asset-model/assets/tls_certificate/) - - - :material-web-refresh:{ .lg .middle } __URL__ --- diff --git a/docs/open_asset_model/properties/dns_property.md b/docs/open_asset_model/properties/dns_property.md index d52b7e8..26643b4 100644 --- a/docs/open_asset_model/properties/dns_property.md +++ b/docs/open_asset_model/properties/dns_property.md @@ -25,4 +25,4 @@ By modeling DNS data with a dedicated property type, `DNSRecordProperty` enables --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/properties/index.md b/docs/open_asset_model/properties/index.md index 6a3e0da..972b73d 100644 --- a/docs/open_asset_model/properties/index.md +++ b/docs/open_asset_model/properties/index.md @@ -86,4 +86,4 @@ Explore the types of data used to enrich and explain assets in the graph: --- -© 2025 Jeff Foley — Licensed under Apache 2.0. \ No newline at end of file +© 2025 Jeff Foley — Licensed under Apache 2.0. diff --git a/docs/open_asset_model/properties/simple_property.md b/docs/open_asset_model/properties/simple_property.md index f0f6a27..864310e 100644 --- a/docs/open_asset_model/properties/simple_property.md +++ b/docs/open_asset_model/properties/simple_property.md @@ -22,4 +22,4 @@ In practice, `SimpleProperty` entries are often used when importing information --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/properties/source_property.md b/docs/open_asset_model/properties/source_property.md index 3face53..5a7bb86 100644 --- a/docs/open_asset_model/properties/source_property.md +++ b/docs/open_asset_model/properties/source_property.md @@ -22,4 +22,4 @@ All Amass engine plugins mark discovered assets and associations between them wi --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/properties/vuln_property.md b/docs/open_asset_model/properties/vuln_property.md index 5a0e34f..90d2a85 100644 --- a/docs/open_asset_model/properties/vuln_property.md +++ b/docs/open_asset_model/properties/vuln_property.md @@ -28,4 +28,4 @@ By standardizing how vulnerability metadata is attached to assets and relations, --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/relations/basic_dns_relation.md b/docs/open_asset_model/relations/basic_dns_relation.md index 30007e1..05f1235 100644 --- a/docs/open_asset_model/relations/basic_dns_relation.md +++ b/docs/open_asset_model/relations/basic_dns_relation.md @@ -27,4 +27,4 @@ In summary, `BasicDNSRelation` enables efficient modeling of essential DNS relat --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/relations/index.md b/docs/open_asset_model/relations/index.md index 890ba02..d1ed132 100644 --- a/docs/open_asset_model/relations/index.md +++ b/docs/open_asset_model/relations/index.md @@ -86,4 +86,4 @@ Learn more about the structure and usage of the model: - [Assoc Tool](../framework_tools/assoc.md) – Using the command-line tool that queries the graph. --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/relations/port_relation.md b/docs/open_asset_model/relations/port_relation.md index 5e24c40..d1824ef 100644 --- a/docs/open_asset_model/relations/port_relation.md +++ b/docs/open_asset_model/relations/port_relation.md @@ -26,4 +26,4 @@ In essence, `PortRelation` adds precise network exposure context to the OAM, let --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/relations/pref_dns_relation.md b/docs/open_asset_model/relations/pref_dns_relation.md index 668e3b6..311f118 100644 --- a/docs/open_asset_model/relations/pref_dns_relation.md +++ b/docs/open_asset_model/relations/pref_dns_relation.md @@ -28,4 +28,4 @@ In summary, `PrefDNSRelation` extends basic DNS modeling by introducing priority --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/relations/simple_relation.md b/docs/open_asset_model/relations/simple_relation.md index 34f60f8..a0d00bf 100644 --- a/docs/open_asset_model/relations/simple_relation.md +++ b/docs/open_asset_model/relations/simple_relation.md @@ -24,4 +24,4 @@ In essence, the `SimpleRelation` is a clean, minimal tool used within the OAM to --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/docs/open_asset_model/relations/srv_dns_relation.md b/docs/open_asset_model/relations/srv_dns_relation.md index cbff3ec..21781af 100644 --- a/docs/open_asset_model/relations/srv_dns_relation.md +++ b/docs/open_asset_model/relations/srv_dns_relation.md @@ -35,4 +35,4 @@ In summary, `SRVDNSRelation` brings full support for SRV record semantics into t --- -*© 2025 Jeff Foley — Licensed under Apache 2.0.* \ No newline at end of file +*© 2025 Jeff Foley — Licensed under Apache 2.0.* diff --git a/mkdocs.yml b/mkdocs.yml index f97e4aa..e6114c0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,6 +120,7 @@ nav: - Assets: - Assets: open_asset_model/assets/index.md - Account: open_asset_model/assets/account.md + - AutnumRecord: open_asset_model/assets/autnum_record.md - AutonomousSystem: open_asset_model/assets/autonomous_system.md - ContactRecord: open_asset_model/assets/contact_record.md - DomainRecord: open_asset_model/assets/domain_record.md @@ -128,10 +129,15 @@ nav: - FundsTransfer: open_asset_model/assets/funds_transfer.md - Identifier: open_asset_model/assets/identifier.md - IPAddress: open_asset_model/assets/ip_address.md + - IPNetRecord: open_asset_model/assets/ipnet_record.md + - Location: open_asset_model/assets/location.md - Netblock: open_asset_model/assets/netblock.md - Organization: open_asset_model/assets/organization.md - Person: open_asset_model/assets/person.md + - Phone: open_asset_model/assets/phone.md - Product: open_asset_model/assets/product.md + - ProductRelease: open_asset_model/assets/product_release.md + - Service: open_asset_model/assets/service.md - TLSCertificate: open_asset_model/assets/tls_certificate.md - URL: open_asset_model/assets/url.md - Relations: From 7638aef26a4f64108612a60b18b50276e399dbc6 Mon Sep 17 00:00:00 2001 From: caffix Date: Wed, 9 Jul 2025 08:55:33 -0400 Subject: [PATCH 28/45] renamed --- docs/{assetDB => asset_db}/assetDB.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{assetDB => asset_db}/assetDB.md (100%) diff --git a/docs/assetDB/assetDB.md b/docs/asset_db/assetDB.md similarity index 100% rename from docs/assetDB/assetDB.md rename to docs/asset_db/assetDB.md From 5ba0aaa9b3cf8075a740b643260b490c7f146d44 Mon Sep 17 00:00:00 2001 From: caffix Date: Wed, 9 Jul 2025 08:55:47 -0400 Subject: [PATCH 29/45] updated --- mkdocs.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index e6114c0..338ab49 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -115,6 +115,13 @@ markdown_extensions: # Page tree nav: - Getting Started: index.md + - Configuration: + - Configuration: open_asset_model/configuration/index.md + - Data Sources: open_asset_model/configuration/data_sources.md + - Asset Database: + - Asset Database: asset_db/index.md + - Triples: asset_db/triples.md + - Transformations: asset_db/transformations.md - Open Asset Model: - Open Asset Model: open_asset_model/index.md - Assets: @@ -153,11 +160,4 @@ nav: - SimpleProperty: open_asset_model/properties/simple_property.md - SourceProperty: open_asset_model/properties/source_property.md - VulnProperty: open_asset_model/properties/vuln_property.md - - Configuration: - - Configuration: open_asset_model/configuration/index.md - - Data Sources: open_asset_model/configuration/data_sources.md - - Asset DB: - - Asset DB: asset_db/index.md - - Triples: asset_db/triples.md - - Transformations: asset_db/transformations.md - Contributing: contributing/contributing.md From 238d92f9f18d67f722c86c44b714c5b90dce6626 Mon Sep 17 00:00:00 2001 From: caffix Date: Sun, 13 Jul 2025 00:28:33 -0400 Subject: [PATCH 30/45] updates --- docs/index.md | 50 +++++++++++++++++++++---- docs/open_asset_model/assets/account.md | 2 +- mkdocs.yml | 7 ++-- 3 files changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3ef4f04..d68e66b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ **OWASP Amass** is an open-source, versatile **attack surface intelligence** framework designed to comprehensively map an organization’s footprint. Built for flexibility and depth, Amass combines advanced data collection, network mapping, and OSINT capabilities to deliver detailed insights into physical and digital assets. -## **//** Overview +## Overview [OWASP Amass](https://github.com/owasp-amass) extends **far beyond basic subdomain enumeration**, offering a comprehensive, automated approach to information gathering that reveals the full scope of an entity's **physical** and **digital** footprint. @@ -19,14 +19,10 @@ __[Unlocking the Power of OWASP Amass]__ by [@jeff_foley](https://x.com/jeff_fol - **Automated Deployment and Enumeration:** Easily deploy Amass with [Docker Compose](https://docs.docker.com/compose/) for quick, automated asset discovery across multiple domains with minimal configuration. -- **Centralized Asset Management with Asset DB:** Use the Asset DB for storing, managing, and retrieving discovered assets, with support for long-term tracking and consistent data collection via the Open Asset Model. +- **Centralized Asset Management with Asset Database:** Use the Asset Database for storing, managing, and retrieving discovered assets, with support for long-term tracking and consistent data collection via the Open Asset Model. - **Scalable and Flexible Infrastructure:** Designed for enterprise environments, [Docker](https://www.docker.com/products/docker-desktop/) enables scalable deployments of Amass, ensuring consistent attack surface management for organizations of any size. -- **Advanced Collection and Monitoring:** The Collections Engine refines the data collection process, while open-source tools like [syslog-ng](https://github.com/syslog-ng/syslog-ng) provide centralized logging, enabling real-time monitoring and diagnostics. - -- **Visualization and Data-Driven Insights:** The latest release features a fully integrated [Grafana](https://grafana.com/oss/grafana/) dashboard, providing dynamic visualization and analysis for deeper attack surface intelligence. - --- ## :octicons-tools-16: Getting Started @@ -44,7 +40,47 @@ Install the Amass swiss army knife executable in your preferred environment. #### Perform the build and installation process ```bash -go install -v github.com/owasp-amass/amass/v5/cmd/amass@main +CGO_ENABLED=0 go install -v github.com/owasp-amass/amass/v5/cmd/amass@main +``` + +At this point, the binary should be in *$GOPATH/bin*. + +#### Install with Libpostal for Street Address Parsing + +**On Ubuntu/Debian** +```bash +sudo apt-get install curl autoconf automake libtool pkg-config +``` + +**On CentOS/RHEL** +```bash +sudo yum install curl autoconf automake libtool pkgconfig +``` + +**On Mac OSX** +```bash +sudo brew install curl autoconf automake libtool pkg-config +``` + +**Installing libpostal** +```bash +git clone https://github.com/openvenues/libpostal.git +cd libpostal +./bootstrap.sh +./configure --datadir=[...some dir with a few GB of space...] +make +sudo make install +``` + +On Linux it's probably a good idea to run. +```bash +sudo ldconfig +``` + +Now, build OWASP Amass with libpostal compiled in for street address parsing. + +```bash +CGO_ENABLED=1 go install -v github.com/owasp-amass/amass/v5/cmd/amass@main ``` At this point, the binary should be in *$GOPATH/bin*. diff --git a/docs/open_asset_model/assets/account.md b/docs/open_asset_model/assets/account.md index f4c00ee..4ff5ed2 100644 --- a/docs/open_asset_model/assets/account.md +++ b/docs/open_asset_model/assets/account.md @@ -69,7 +69,7 @@ acct --o idRel idRel --> ident org["Organization"] -person["Person] +person["Person"] user@{ shape: braces, label: "user" } acct --o user user --> org diff --git a/mkdocs.yml b/mkdocs.yml index 338ab49..837b494 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,11 +2,11 @@ # mkdocs serve # mkdocs gh-deploy -site_name: OWASP Amass +site_name: OWASP Amass Project site_url: https://owasp-amass.github.io/docs/ repo_name: OWASP Amass repo_url: https://github.com/owasp-amass/amass -site_description: "In-depth OSINT collection and external attack surface mapping " +site_description: "In-depth OSINT collection and external attack surface mapping" site_author: OWASP Amass Contributors remote_branch: gh-pages @@ -118,10 +118,11 @@ nav: - Configuration: - Configuration: open_asset_model/configuration/index.md - Data Sources: open_asset_model/configuration/data_sources.md + - Transformations: asset_db/transformations.md - Asset Database: - Asset Database: asset_db/index.md + - PostgreSQL: asset_db/postgres.md - Triples: asset_db/triples.md - - Transformations: asset_db/transformations.md - Open Asset Model: - Open Asset Model: open_asset_model/index.md - Assets: From e1c8c177de469baa589dd5d0b1d725f632ef853b Mon Sep 17 00:00:00 2001 From: caffix Date: Sun, 13 Jul 2025 15:26:05 -0400 Subject: [PATCH 31/45] small change to Ubuntu prerequisities --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index d68e66b..318a5a2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,7 +49,7 @@ At this point, the binary should be in *$GOPATH/bin*. **On Ubuntu/Debian** ```bash -sudo apt-get install curl autoconf automake libtool pkg-config +sudo apt-get install curl autoconf make automake libtool pkg-config ``` **On CentOS/RHEL** @@ -57,7 +57,7 @@ sudo apt-get install curl autoconf automake libtool pkg-config sudo yum install curl autoconf automake libtool pkgconfig ``` -**On Mac OSX** +**On MacOS** ```bash sudo brew install curl autoconf automake libtool pkg-config ``` From fb1c366f4a9a7ff04ac002b4f1ba49e3496fa4e8 Mon Sep 17 00:00:00 2001 From: caffix Date: Sun, 13 Jul 2025 17:48:50 -0400 Subject: [PATCH 32/45] fixed the Homebrew instructions --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 318a5a2..b2e864a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -98,7 +98,7 @@ The OWASP Amass Project maintains a **Homebrew** package. The following two commands will install Amass into your environment: ```bash -brew tap owasp-amass/amass +brew tap owasp-amass/homebrew-amass brew install amass ``` From 8c03703bc66182a30632678e106c683ec32c7894 Mon Sep 17 00:00:00 2001 From: caffix Date: Mon, 14 Jul 2025 00:19:38 -0400 Subject: [PATCH 33/45] added instructions for using the Official Amass Docker image --- docs/index.md | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index b2e864a..c2a3b11 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,6 @@ [OWASP Amass](https://github.com/owasp-amass) extends **far beyond basic subdomain enumeration**, offering a comprehensive, automated approach to information gathering that reveals the full scope of an entity's **physical** and **digital** footprint. - ??? info "Open Asset Model (OAM)" The [Open Asset Model](https://owasp-amass.github.io/docs/open-asset-model/) expands traditional specifications by modeling both the **physical** and **digital** structure of a target's asset landscape. Defining **asset types**, their unique **properties**, and the **relationships** that join them, the `OAM` compiles a comprehensive view of the attack surface from an adversarial perspective. @@ -102,6 +101,37 @@ brew tap owasp-amass/homebrew-amass brew install amass ``` +### Execute using the Official Amass Docker Image + +#### Prerequisites + +Before you begin, make sure you have the following installed on your system: + +- **Docker:** Up-to-date intallation running on your system. You can download it from the [Docker Official Website](https://www.docker.com/products/docker-desktop/). + +#### Step 1: Pull the Amass Docker Image + +```bash +docker pull owaspamass/amass:latest +``` + +#### Step 2: Give the Image a Convenient Tag + +```bash +docker tag owaspamass/amass:5.0.0 amass:latest +``` + +#### Step 3: Execute Amass using the Container + +The volume mount allows the information collected to be stored outside of the container. + +```bash +docker run --rm -it -v ~/.config/amass:/.config/amass amass:latest enum -d owasp.org +``` + +!!! Warning + The example above mounts the Amass configuration directory on Linux. The location of this directory can be different on other operating systems. + ### Containerized Execution within Docker Compose Follow these steps to set up Amass using [Docker Compose](https://docs.docker.com/compose/): @@ -140,7 +170,6 @@ nano assetdb.env # (1)! 1. You can replace `nano` with your preferred text editor, like `vim` or `code` for Visual Studio Code. - **> Set the Passwords:** In the `assetdb.env` file, locate the lines for `POSTGRES_PASSWORD` and `AMASS_PASSWORD`. Update them to assign new values. @@ -148,8 +177,8 @@ In the `assetdb.env` file, locate the lines for `POSTGRES_PASSWORD` and `AMASS_P For example: ```bash -POSTGRES_PASSWORD= your_new_postgres_password -AMASS_PASSWORD= your_new_amass_password +POSTGRES_PASSWORD=your_new_postgres_password +AMASS_PASSWORD=your_new_amass_password ``` !!! Warning @@ -163,7 +192,6 @@ After editing, save the file: - If you're using **vim**: Press `Esc`, then type `:wq` and hit `Enter`. - **> Modify the `config.yaml` File:** Open the `config.yaml` file to set the database password to the one you just assigned as `AMASS_PASSWORD`. @@ -188,7 +216,6 @@ options: As before, save the changes using your preferred text editor. - !!! info "Update the Data Sources" If you want to configure data sources, you can modify the `datasources.yaml` file. Open it with: ```bash @@ -208,7 +235,6 @@ docker compose run --rm enum -active -d example.org # (1)! 1. If the build process times out, simply execute the command again to resume. - #### :material-update: Update Process for the Compose Environment **> Make the local repo your current working directory:** From 31393eaa049d50bc5ac4510ab8b76f768a8c7385 Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 17 Jul 2025 17:19:35 -0400 Subject: [PATCH 34/45] added the documentation for the verified_for relationship --- docs/open_asset_model/assets/fqdn.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/open_asset_model/assets/fqdn.md b/docs/open_asset_model/assets/fqdn.md index d1eb437..39ca9c8 100644 --- a/docs/open_asset_model/assets/fqdn.md +++ b/docs/open_asset_model/assets/fqdn.md @@ -61,6 +61,13 @@ domrec["DomainRecord"] regrel@{ shape: braces, label: "registration"} fqdn1 --o regrel regrel --> domrec + +org["Organization (e.g. Google LLC)"] +serv2["Service (e.g. Google Workspace)"] +verified@{ shape: braces, label: "verified_for" } +fqdn1 --o verified +verified --> org +verified --> serv2 ``` --- @@ -73,6 +80,7 @@ regrel --> domrec | [`SimpleRelation`](../relations/simple_relation.md) | `node` | `FQDN` | Links a DNS zone apex to nodes within the zone | | [`PortRelation`](../relations/port_relation.md) | `port` | [`Service`](./service.md) | Represents a port at the FQDN with a responding service | | [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`DomainRecord`](./domain_record.md) | Links a root domain to its associated registration data | +| [`SimpleRelation`](../relations/simple_relation.md) | `verified_for` | [`Organization`](./organization.md), [`Service`](./service.md) | Evidence was discovered of a business or technical relationship | --- From 9952d0384e2da3e5793bcc072d2285055dd105d0 Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 17 Jul 2025 18:51:19 -0400 Subject: [PATCH 35/45] renamed the default Asset Database docs page --- docs/asset_db/{assetDB.md => index.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/asset_db/{assetDB.md => index.md} (100%) diff --git a/docs/asset_db/assetDB.md b/docs/asset_db/index.md similarity index 100% rename from docs/asset_db/assetDB.md rename to docs/asset_db/index.md From 56a999c2362e199ce0e4bff84affe5ced35ed13a Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 17 Jul 2025 18:51:33 -0400 Subject: [PATCH 36/45] initial commit --- docs/asset_db/postgres.md | 107 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/asset_db/postgres.md diff --git a/docs/asset_db/postgres.md b/docs/asset_db/postgres.md new file mode 100644 index 0000000..ab91c5b --- /dev/null +++ b/docs/asset_db/postgres.md @@ -0,0 +1,107 @@ +# Setting Up a PostgreSQL Database for OWASP Amass + +The OWASP Amass framework can store collected data in a PostgreSQL database. This page walks you through the recommended setup process, including environment variables, database initialization, and configuration in your `config.yaml` file. + +> **Note:** These instructions assume PostgreSQL is already installed and running on your system (e.g., `localhost:5432`). You’ll need access to a user with sufficient privileges (typically `postgres`). + +## 1. Define Environment Variables + +Before running the setup commands, export the following environment variables to define your database, user, and passwords. These values will be used in the setup process and your Amass configuration. + +```bash +export POSTGRES_USER=postgres +export POSTGRES_PASSWORD=postgres +export AMASS_DB=assetdb +export AMASS_USER=amass +export AMASS_PASSWORD=amass4OWASP +``` + +??? info "Secrets Management" + Consider storing these in a `.env` file and loading them with `source .env` to avoid retyping. Never commit secrets to version control. + +## 2. Create the Amass Database and User + +Run the following commands in your shell to initialize the database and create a dedicated user for Amass. This uses the `psql` CLI with inline SQL for automation. + +```bash +# Add single quotes around the password to handle special characters +export TEMPPASS="'$AMASS_PASSWORD'" + +# Create the database and user +psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" <<-EOSQL + \getenv assetdb AMASS_DB + \getenv username AMASS_USER + \getenv password TEMPPASS + + CREATE DATABASE :assetdb; + ALTER DATABASE :assetdb SET timezone TO 'UTC'; + CREATE USER :username WITH PASSWORD :password; +EOSQL +``` + +This will: + +* Create the `assetdb` database +* Set its default timezone to UTC (recommended for consistency) +* Create a new user (`amass`) with the specified password + +## 3. Enable Extensions and Grant Privileges + +Next, connect to the new database and enable the required PostgreSQL extension and assign privileges to the Amass user. + +```bash +psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$AMASS_DB" <<-EOSQL + \getenv username AMASS_USER + + CREATE EXTENSION pg_trgm SCHEMA public; + + GRANT USAGE ON SCHEMA public TO :username; + GRANT CREATE ON SCHEMA public TO :username; + GRANT ALL ON ALL TABLES IN SCHEMA public TO :username; +EOSQL +``` + +This will: + +* Enable the `pg_trgm` extension (used by Amass for efficient fuzzy string matching) +* Grant the necessary privileges for Amass to create and manage data within the `public` schema + +## 4. Update Your Amass Configuration + +Once your database is set up, update your Amass `config.yaml` file with the connection string: + +```yaml +options: + # Be sure to replace the credentials with values matching your environment + database: "postgres://amass:amass4OWASP@127.0.0.1:5432/assetdb" +``` + +??? info "Security Reminder" + Avoid committing passwords to source control. Where possible, consider injecting the connection string using an environment variable (e.g., `${AMASS_DB_URI}`). + +## 5. Test the Connection + +You can test whether the Amass framework is successfully connecting to your PostgreSQL database by running a standard enumeration command: + +```bash +amass enum -config config.yaml +``` + +If the configuration is correct, the collected data will be stored in the PostgreSQL backend you configured. + +## ✅ You're Done! + +Amass is now ready to store data in your PostgreSQL database. This enables you to persist, analyze, and query discovered assets using SQL or integrate with other tooling and dashboards. + +## Troubleshooting Tips + +* **Connection Refused?** Ensure PostgreSQL is listening on `127.0.0.1:5432` and that the database server is running. +* **Authentication Failed?** Double-check your environment variable values, especially the user and password. +* **Extension Errors?** Make sure the `pg_trgm` extension is available and installed. You can check with `\dx` in `psql`. + +## See Also + +* [Amass Configuration](../configuration/configuration.md) +* [PostgreSQL Documentation](https://www.postgresql.org/docs/current/index.html) +* [PostgreSQL `pg_trgm` Extension Docs](https://www.postgresql.org/docs/current/pgtrgm.html) +* [Managing Environment Variables Securely](https://direnv.net/) From f3d5d335cfb5d10efa15c57e6da1d31bad88fb14 Mon Sep 17 00:00:00 2001 From: The-Inceptions <83852285+The-Inceptions@users.noreply.github.com> Date: Fri, 18 Jul 2025 03:21:04 +0000 Subject: [PATCH 37/45] Added configuration and data sources mark down This should cover everything there is to know about the configuration + datasources for both users and developers. --- docs/configuration/datasources.md | 89 +++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/configuration/datasources.md diff --git a/docs/configuration/datasources.md b/docs/configuration/datasources.md new file mode 100644 index 0000000..00f8e4c --- /dev/null +++ b/docs/configuration/datasources.md @@ -0,0 +1,89 @@ +# Amass Data Sources Configuration + +This document explains how to configure external data sources for Amass using the `datasources.yaml` file. Data sources provide additional information for enumeration and require credentials for access. + +> **Note:** Some data sources require a paid subscription or API key to access advanced features. Using paid or premium data sources can unlock extra capabilities and may provide a better experience for the Amass engine, including more comprehensive results and faster queries. + +--- + +## Data Sources Configuration: `datasources.yaml` + +This file defines which external data sources Amass will use and their credentials. + +### `global_options` + +Set global defaults for all data sources. + +- `minimum_ttl`: Default TTL for data source results (in minutes). + +**Format:** + +```yaml +# these are the global options related to data sources. +global_options: +# minimum_ttl is the default used when datasources don't specify a larger ttl value. + minimum_ttl: 1440 #one day +``` + +### `datasources` + +The `datasources` section is a list of external data sources Amass will use. Each entry can specify credentials, TTL, and multiple accounts. All fields are optional except for `name`. + +**Supported Fields:** + +- `name` (string, required): The name of the data source (e.g., `Shodan`, `CIRCL`). +- `ttl` (int, optional): Time-to-live for results from this data source, in minutes. If omitted, the global minimum TTL is used. +- `creds` (object, optional): A map of account names to credential sets. You can name the account key anything (e.g., `account`, `personal`, `work`, `default`), which helps organize multiple credential sets for the same data source. Amass will accept any key name here. + - `` (object): The account name (arbitrary string) for this credential set. + - `apikey` (string, optional): API key for the data source. + - `username` (string, optional): Username for authentication. + - `password` (string, optional): Password for authentication. + - `secret` (string, optional): Secret value for authentication (used by some APIs). + +**Format:** + +```yaml +datasources: + - name: + ttl: # optional + creds: + : # You can name this key anything (e.g., 'account', 'personal', 'work') + apikey: + username: + password: + secret: +``` + +**Example:** + +```yaml +datasources: + - name: Shodan + ttl: 10080 + creds: + account: + apikey: YOUR_SHODAN_API_KEY + - name: CIRCL + creds: + account: + username: YOUR_USERNAME + password: YOUR_PASSWORD +``` + +--- + +## Tips + +- Comment or uncomment sections in YAML to enable/disable features. +- Use relative paths for wordlists and data source files for portability. +- Always keep your API keys and credentials secure. + +For more details, see the [example configuration files](https://github.com/owasp-amass/amass/tree/main/resources) and the [Amass documentation](https://github.com/owasp-amass/amass/wiki). + +--- + +## Advanced Configuration Details + +- **Custom Data Source Credentials:** In the data source config, [credentials are stored as a map](https://github.com/owasp-amass/amass/blob/f46cda51b3e9a701a0498eafa0e9f82a0f26e864/config/datasrcs.go#L16-L29) (`map[string]*Credentials`). This allows you to define multiple credential sets per data source in YAML, and Amass will deserialize them into Go structs. You can add new credential types as needed for custom integrations. + +**Tip:** This flexibility is powerful for advanced users and developers, but be careful—unsupported or misspelled options may be silently ignored unless handled in code. From 6c3fb27b7a2d5dcb3f4be48d23101924fe6d9fcd Mon Sep 17 00:00:00 2001 From: The-Inceptions <83852285+The-Inceptions@users.noreply.github.com> Date: Fri, 18 Jul 2025 03:22:18 +0000 Subject: [PATCH 38/45] Added configuration and data sources mark down This should cover everything there is to know about the configuration + datasources for both users and developers. --- docs/configuration/configuration.md | 224 ++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 8b13789..b24eac7 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -1 +1,225 @@ +# Amass Configuration Guide + +This document explains the structure and options available in Amass configuration files. Amass uses YAML files to define its scan scope, data sources, and operational options. Understanding these files will help you customize Amass for your use case. + +--- + +## Main Configuration: `config.yaml` + +The main configuration file, typically named `config.yaml`, controls the scope of your scan, scanning options, and transformation rules. Below is a breakdown of its main sections: + +### `scope` + +The `scope` section defines the targets and boundaries for enumeration and scanning. Each field is parsed and normalized by Amass, supporting a variety of input formats. + +**Supported Fields:** + +- `domains` (array of strings): Registered domain names in scope (e.g., `owasp.org`). +- `ips` (array of strings): IP addresses in scope. Supports single IPs (e.g., `192.0.2.1`), dash-ranges (e.g., `192.168.0.3-8`), and full ranges (e.g., `192.168.0.10-192.168.0.20`). +- `asns` (array of strings): Autonomous System Numbers (ASNs) in scope (e.g., `AS15169`). +- `cidrs` (array of strings): CIDR ranges in scope (e.g., `192.0.2.0/24`). +- `ports` (array of ints): Ports to be used when actively scanning services (e.g., `80`, `443`, `8080`). +- `blacklist` (array of strings): Subdomains to be excluded from results. + +**Example:** + +```yaml +scope: + domains: + - owasp.org + ips: + - 192.0.2.1 + - 192.168.0.10-192.168.0.20 + cidrs: + - 192.0.2.0/24 + ports: + - 80 + - 443 + blacklist: + - test.owasp.org +``` + +### `seed` + +The `seed` section is optional and allows you to specify an initial set of domains, IPs, CIDRs, ASNs, ports, and blacklist entries. If provided, Amass uses `seed` to initialize the scan scope. If the `scope` section is not specified, the `seed` will also be used as the scope. Otherwise, `seed` and `scope` are treated as separate entities, and both can be specified independently. + +**Supported Fields:** + +- `domains` (array of strings): Registered domain names to seed the scan (e.g., `owasp.org`). +- `ips` (array of strings): IP addresses to seed the scan. Supports single IPs, dash-ranges, and full ranges. +- `asns` (array of strings): Autonomous System Numbers to seed the scan (e.g., `AS15169`). +- `cidrs` (array of strings): CIDR ranges to seed the scan (e.g., `192.0.2.0/24`). +- `ports` (array of ints): Ports to be used when actively scanning services. +- `blacklist` (array of strings): Subdomains to be excluded from results. + +**Example:** + +```yaml +seed: + domains: + - owasp.org + ips: + - 192.0.2.1 + - 192.168.0.10-192.168.0.20 + cidrs: + - 192.0.2.0/24 + ports: + - 80 + - 443 + blacklist: + - test.owasp.org +``` + +### `options` + +The `options` section controls data sources, brute force, alterations, engine/database connections, and default values for transforms. Each option is handled by dedicated loader functions in Amass, and must match the expected type. + +**Supported Options:** + +- `datasources` (string): Path to the data sources YAML file. Required for external data source integration. + - For information about the format and fields in this file, see the [Data Sources Configuration](datasources.md) section. +- `engine` (string): URL for the Amass engine API (e.g., `http://127.0.0.1:4000/graphql`). +- `database` (string): Database connection string (e.g., `bolt://neo4j:amass4OWASP@neo4j:7687/neo4j` or `postgres://amass:amass4OWASP@assetdb:5432/assetdb`). +- `bruteforce` (object): + - `enabled` (bool): Enable or disable brute force subdomain enumeration. + - `wordlists` (array of strings): List of wordlist files for brute forcing. Each file can be plain text or gzipped. +- `alterations` (object): + - `enabled` (bool): Enable or disable name alteration techniques. + - `wordlists` (array of strings): List of wordlist files for alterations. Each file can be plain text or gzipped. +- `default_transform_values` (object): + - `ttl` (int): Default time-to-live for transform results (in minutes). + - `confidence` (int): Default confidence value (percentage). + - `priority` (int): Default priority value. +- `active` (bool): Enable active enumeration (e.g., zone transfers, certificate checks). +- `rigid_boundaries` (bool): Enforce strict scope boundaries for enumeration. + +> **Notice:** Relative paths are relative to the config file location. + +**Example:** + +```yaml +options: + datasources: "./datasources.yaml" + engine: "http://127.0.0.1:4000/graphql" + database: "bolt://neo4j:amass4OWASP@neo4j:7687/neo4j" + bruteforce: + enabled: false + wordlists: + - "./namelist.txt" + alterations: + enabled: false + wordlists: + - "./alterations.txt" + default_transform_values: + ttl: 1440 + confidence: 50 + priority: 5 + active: true + rigid_boundaries: false +``` + +#### Environment Variables for Engine and Database + +Amass supports configuring the Engine API and Database connection using environment variables as an alternative to specifying the `engine` or `database` URI in the `options` section. **If you specify a URI in the config file for either `engine` or `database`, Amass will NOT use the corresponding environment variables for that object.** There is no merging of environment variables and config values per object—it's either one or the other for each. + +**Engine API Environment Variables:** + +- `AMASS_ENGINE_USER`: Username for Engine API authentication +- `AMASS_ENGINE_PASSWORD`: Password for Engine API authentication +- `AMASS_ENGINE_HOST`: Host for the Engine API (default: `localhost`) +- `AMASS_ENGINE_PORT`: Port for the Engine API (default: `4000`) +- `AMASS_ENGINE_PATH`: Path for the Engine API (default: `graphql`) +- `AMASS_ENGINE_SCHEME`: Scheme for the Engine API (`http` or `https`, default: `http`) + +**Database Environment Variables:** + +- `AMASS_DB_USER`: Username for the database +- `AMASS_DB_PASSWORD`: Password for the database +- `AMASS_DB_HOST`: Host for the database (default: `localhost`) +- `AMASS_DB_PORT`: Port for the database (default: `5432`) +- `AMASS_DB_NAME`: Database name (default: `assetdb`) + +**Important:** + +- If you set the `engine` or `database` URI in the config file, Amass will use only that value and ignore the related environment variables for that object. +- You cannot mix or merge environment variable values with a URI specified in the config for either the Engine API or the Database. For now, it is one or the other, per object. + +--- + +### `transformations` + +The `transformations` section controls how assets should be proccessed, how long results from specific transforms are considered valid (TTL), and the minimum confidence level. This can be customized per entity and transform type. + +- Each transformation key is parsed as `->`. Amass validates these against the Open Asset Model (OAM) and ensures there are no conflicts (e.g., you can't have both `FQDN->ALL` and `FQDN->none`). You can set `ttl`, `confidence`, `priority`, and `exclude` for each transformation. +- If a transformation omits `ttl`, `confidence`, or `priority`, Amass uses the values from `default_transform_values` in `options`. +- You can add or modify transformations in Go by editing the `Config.Transformations` map and calling validation methods. + +**Supported Format:** + +- `->` (object): + - `ttl` (int, optional): Time-to-live for this transformation result, in minutes. + - `confidence` (int, optional): Confidence value for this transformation (percentage). + - `priority` (int, optional): Priority value for this transformation. + - `exclude` (array of strings, optional): List of transforms to exclude. +In this example, the TTL and confidence settings will only apply when the transformation is handled by the plugin named `myplugin`. + +> **Tip:** Use `ALL` as the transform to apply the rule to all transforms for a given entity. + +**Example:** + +```yaml +transformations: + FQDN->DNS: + ttl: 1440 + FQDN->DomainRecord: + ttl: 43200 + Account->ALL: + ttl: 1080 +``` + +**Granular Example (per plugin):** +[Amass handles plugin level granularity](https://github.com/owasp-amass/amass/blob/main/engine/plugins/support/support.go#L91C1-L105C1). You can specify transformation rules as granularly as you want—even down to a single plugin. If you use the plugin's name as the `` in your `->` transformation key, Amass will apply that rule only for that plugin. This enables highly targeted configuration and fine-grained control over how results are handled for each plugin. + +```yaml +transformations: + FQDN->myplugin: + ttl: 60 + confidence: 90 +``` + +--- + +For more details, see the [example configuration files](https://github.com/owasp-amass/amass/tree/main/resources) and the [Amass documentation](https://github.com/owasp-amass/amass/wiki). + +--- + +## How Amass Loads Configuration + +Amass supports flexible configuration loading. allowing you to control settings via YAML files, environment variables, and programmatic overrides. + +### Configuration Loading Order + +1. **Explicit file**: If you specify a config file path (e.g., with `-config`), it is loaded first. +2. **Environment variable**: If the `AMASS_CONFIG` environment variable is set, its path is used. +3. **Default locations**: Amass looks for `config.yaml` in the output directory (usually `~/.config/amass/`) or `/etc/amass/config.yaml` on Linux. + +### Programmatic Configuration + +If you use Amass as a Go library, you can construct a `Config` object directly in code, set fields, and call methods like `LoadSettings()` or `AcquireConfig()` to merge YAML and programmatic settings. + +--- + +## Advanced Configuration Details + +Amass uses Go interfaces and flexible types in its configuration structs to allow for advanced and custom settings: + +- **Flexible Options:** [The `options` section in YAML is loaded into a `map[string]interface{}`](https://github.com/owasp-amass/amass/blob/f46cda51b3e9a701a0498eafa0e9f82a0f26e864/config/config.go#L67). This means you can add arbitrary keys and values—even ones not officially documented. If Amass has a loader for your option (like `active`, `rigid_boundaries`, or future features), it will be parsed and used (e.g., check out the code for [loading the `database` option](https://github.com/owasp-amass/amass/blob/f46cda51b3e9a701a0498eafa0e9f82a0f26e864/config/graphdb.go#L40-L57)). Otherwise, you can access these values programmatically if you use Amass as a library. + +- **Scope Parsing:** The `Scope` struct uses fields like `PortsRaw []interface{}` so you can specify ports as single values, lists, or ranges in YAML. Amass normalizes these internally, so you have flexibility in how you define scope. + +- **Loader Functions:** After deserialization, [Amass runs a series of loader functions to process, validate, and normalize settings](https://github.com/owasp-amass/amass/blob/f46cda51b3e9a701a0498eafa0e9f82a0f26e864/config/config.go#L292-L302). This means you can experiment with new options or override behaviors by adding new keys to your YAML, as long as you handle them in your own fork or via the Go API. + +- **Programmatic Access:** If you use Amass as a Go library, you can read, modify, or extend the config structs directly, including any custom or experimental options you add to your YAML. + +> **Tip:** This flexibility is powerful for advanced users and developers, but be careful—unsupported or misspelled options may be silently ignored unless handled in code. From 7d61e85ae9b2d7c913f58a809d6e6f243718e771 Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 18 Jul 2025 17:50:30 -0400 Subject: [PATCH 39/45] file names changed --- docs/configuration/{datasources.md => data_sources.md} | 0 docs/configuration/{configuration.md => index.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/configuration/{datasources.md => data_sources.md} (100%) rename docs/configuration/{configuration.md => index.md} (100%) diff --git a/docs/configuration/datasources.md b/docs/configuration/data_sources.md similarity index 100% rename from docs/configuration/datasources.md rename to docs/configuration/data_sources.md diff --git a/docs/configuration/configuration.md b/docs/configuration/index.md similarity index 100% rename from docs/configuration/configuration.md rename to docs/configuration/index.md From 3390c7708de8f151971cf193b111372869c2fd3c Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 18 Jul 2025 17:50:44 -0400 Subject: [PATCH 40/45] initial commit --- docs/configuration/transformations.md | 133 ++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/configuration/transformations.md diff --git a/docs/configuration/transformations.md b/docs/configuration/transformations.md new file mode 100644 index 0000000..0bea9ee --- /dev/null +++ b/docs/configuration/transformations.md @@ -0,0 +1,133 @@ +# :material-auto-fix: Asset Transformations Configuration + +The `transformations` section of the OWASP Amass `config.yaml` file is one of the most powerful parts of the collection engine. It controls **how data flows through the system**, defines **which types of assets can be transformed into others**, and sets **constraints like freshness (TTL), trustworthiness (confidence), and urgency (priority)** on those transformations. + +This section empowers users to **customize and optimize their data collection workflows** based on their goals, risk tolerance, and update requirements. + +## :material-help-circle-outline: What Are Transformations? + +In Amass, the data collection process is modeled as a pipeline of **asset transformations**. Each asset observed (like an IP address, domain, ASN, etc.) can trigger **handlers**, which attempt to enrich, correlate, or expand on that asset type by transforming it into new assets. + +For example: +- A discovered `FQDN` might trigger a handler to look up its DNS records (`FQDN -> DNS`) +- A known `AutonomousSystem` could be transformed into its RDAP metadata (`AutonomousSystem -> RDAP`) +- A `Product` seen on a web service might lead to discovery of its `ProductRelease` metadata + +The `transformations` section defines: +- **Which transformations are allowed** +- **How frequently** each transformation should be retried (`ttl`) +- **How much confidence** the system should have in the results (`confidence`) +- **How important** the transformation is (`priority`) + +## :material-cog-outline: Configuration Overview + +Here's the structure of a typical configuration: + +```yaml +options: + default_transform_values: + ttl: 1440 # in minutes (default is 1 day) + confidence: 50 # default confidence threshold (0–100%) + priority: 5 # default priority level (1=low, 10=high) + +transformations: + FQDN->DNS: + ttl: 1440 + AutonomousSystem->RDAP: + ttl: 43200 # 30 days + Identifier->GLEIF: + ttl: 43200 + Product->ALL: + ttl: 10080 # 7 days +``` + +### \:gear: `default_transform_values` + +This section defines fallback values used when no custom values are given for a transformation. + +| Key | Type | Description | +| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- | +| `ttl` | integer | Time-to-live (in minutes) for data freshness. If expired, the data will be fetched again from the source instead of reused. | +| `confidence` | integer | Minimum confidence (0–100%) required to accept the result of a transformation. | +| `priority` | integer | Priority score (1=lowest, 10=highest) that may influence queue ordering in some future extensions. | + +## \:hammer\_and\_wrench: Defining Transformations + +Each transformation follows this format: + +```yaml +->: + ttl: # Optional override of default + confidence: # Optional override + priority: # Optional override +``` + +Use `->ALL` as a wildcard to enable **all available transformations from a given source asset type**. + +Example: + +```yaml +FQDN->ALL: +``` + +This enables all known FQDN transformations (e.g., `FQDN->IPAddress`, `FQDN->DomainRecord`, etc.). + +## \:page\_facing\_up: Example Config Breakdown + +```yaml +transformations: + FQDN->DNS: + ttl: 1440 # 1 day + FQDN->DomainRecord: + ttl: 43200 # 30 days + IPAddress->ALL: + TLSCertificate->ALL: + ttl: 10080 # 7 days +``` + +### Explanation: + +* **FQDN->DNS**: Amass will try to resolve DNS for fully qualified domain names once per day. +* **FQDN->DomainRecord**: Domain ownership records are more stable, so these are refreshed every 30 days. +* **IPAddress->ALL**: All available transformations for IPs are enabled (e.g., geolocation, RDAP, reverse DNS). +* **TLSCertificate->ALL**: Certificates fetched from services are checked weekly. + +## \:material-refresh: What is `ttl`? + +`ttl` (Time To Live) controls **how often a transformation can be retried** from the original source: + +* If the data is **still fresh** (within TTL), Amass will use the previously stored result from the database. +* If the TTL has **expired**, the handler will attempt to **re-run the transformation**, such as querying the data source again. + +This ensures the system avoids unnecessary queries and controls bandwidth/load. + +## \:material-shield-check: What is `confidence`? + +`confidence` helps Amass **filter out noisy or speculative results**. Some plugins or handlers may return results with associated confidence scores. + +* If a handler returns a transformation with `confidence: 40`, and your threshold is `50`, **it will be ignored**. +* Use this to reduce false positives or to tune behavior in environments where high data quality is crucial. + +## \:material-star: What is `priority`? + +The `priority` value is a **relative score (1–10)** that can help inform which transformations are more important. While not strictly enforced in the engine today, this allows **future prioritization of more urgent or valuable tasks**—like scanning attack surfaces or refreshing high-risk domains. + +## \:material-clipboard-list-outline: Tips and Best Practices + +* ✅ Use `->ALL` to simplify enabling all known transformations for an asset type. +* ✅ Use higher TTLs (e.g., 30+ days) for records that rarely change (e.g., `RDAP`, `GLEIF`, `DomainRecord`). +* ⚠️ Keep `ttl` low (e.g., 60–1440 min) for time-sensitive records like DNS, services, or IP geolocation. +* ✅ Set `confidence` thresholds higher (e.g., 70–90) in production pipelines where trust is critical. +* ✅ Consider adjusting `priority` for critical infrastructure or high-value assets. + +## \:material-rocket-launch: Summary + +The `transformations` section of the Amass configuration lets users **shape the intelligence collection process**, optimize for **freshness vs. efficiency**, and **control data quality** through TTLs and confidence scoring. + +It is a key part of how Amass turns passive and active discoveries into structured asset graphs that can drive attack surface monitoring, red teaming, or asset attribution. + +--- + +For a full list of supported asset types, refer to the [Open Asset Model documentation](../open_asset_model/index.md). + +*© 2025 Jeff Foley — Licensed under Apache 2.0.* From 7a1647cdaa4dbe3d13f4f1b407b6f682d1f8c629 Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 18 Jul 2025 17:53:23 -0400 Subject: [PATCH 41/45] fixes to the page tree --- mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 837b494..b0df656 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -116,9 +116,9 @@ markdown_extensions: nav: - Getting Started: index.md - Configuration: - - Configuration: open_asset_model/configuration/index.md - - Data Sources: open_asset_model/configuration/data_sources.md - - Transformations: asset_db/transformations.md + - Configuration: configuration/index.md + - Data Sources: configuration/data_sources.md + - Transformations: configuration/transformations.md - Asset Database: - Asset Database: asset_db/index.md - PostgreSQL: asset_db/postgres.md From 6861f58fd46f11dad7a11aff9186892bc82cb7ef Mon Sep 17 00:00:00 2001 From: caffix Date: Fri, 18 Jul 2025 17:57:13 -0400 Subject: [PATCH 42/45] fixes --- docs/configuration/transformations.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/configuration/transformations.md b/docs/configuration/transformations.md index 0bea9ee..7a2e8e1 100644 --- a/docs/configuration/transformations.md +++ b/docs/configuration/transformations.md @@ -41,7 +41,7 @@ transformations: ttl: 10080 # 7 days ``` -### \:gear: `default_transform_values` +### :gear: `default_transform_values` This section defines fallback values used when no custom values are given for a transformation. @@ -51,7 +51,7 @@ This section defines fallback values used when no custom values are given for a | `confidence` | integer | Minimum confidence (0–100%) required to accept the result of a transformation. | | `priority` | integer | Priority score (1=lowest, 10=highest) that may influence queue ordering in some future extensions. | -## \:hammer\_and\_wrench: Defining Transformations +## :hammer_and_wrench: Defining Transformations Each transformation follows this format: @@ -72,7 +72,7 @@ FQDN->ALL: This enables all known FQDN transformations (e.g., `FQDN->IPAddress`, `FQDN->DomainRecord`, etc.). -## \:page\_facing\_up: Example Config Breakdown +## :page_facing_up: Example Config Breakdown ```yaml transformations: @@ -92,7 +92,7 @@ transformations: * **IPAddress->ALL**: All available transformations for IPs are enabled (e.g., geolocation, RDAP, reverse DNS). * **TLSCertificate->ALL**: Certificates fetched from services are checked weekly. -## \:material-refresh: What is `ttl`? +## :material-refresh: What is `ttl`? `ttl` (Time To Live) controls **how often a transformation can be retried** from the original source: @@ -101,18 +101,18 @@ transformations: This ensures the system avoids unnecessary queries and controls bandwidth/load. -## \:material-shield-check: What is `confidence`? +## :material-shield-check: What is `confidence`? `confidence` helps Amass **filter out noisy or speculative results**. Some plugins or handlers may return results with associated confidence scores. * If a handler returns a transformation with `confidence: 40`, and your threshold is `50`, **it will be ignored**. * Use this to reduce false positives or to tune behavior in environments where high data quality is crucial. -## \:material-star: What is `priority`? +## :material-star: What is `priority`? The `priority` value is a **relative score (1–10)** that can help inform which transformations are more important. While not strictly enforced in the engine today, this allows **future prioritization of more urgent or valuable tasks**—like scanning attack surfaces or refreshing high-risk domains. -## \:material-clipboard-list-outline: Tips and Best Practices +## :material-clipboard-list-outline: Tips and Best Practices * ✅ Use `->ALL` to simplify enabling all known transformations for an asset type. * ✅ Use higher TTLs (e.g., 30+ days) for records that rarely change (e.g., `RDAP`, `GLEIF`, `DomainRecord`). @@ -120,7 +120,7 @@ The `priority` value is a **relative score (1–10)** that can help inform which * ✅ Set `confidence` thresholds higher (e.g., 70–90) in production pipelines where trust is critical. * ✅ Consider adjusting `priority` for critical infrastructure or high-value assets. -## \:material-rocket-launch: Summary +## :material-rocket-launch: Summary The `transformations` section of the Amass configuration lets users **shape the intelligence collection process**, optimize for **freshness vs. efficiency**, and **control data quality** through TTLs and confidence scoring. From 5c0006e03aa3dffe6fecc9907bae5587e4bab781 Mon Sep 17 00:00:00 2001 From: caffix Date: Wed, 30 Jul 2025 20:20:12 -0400 Subject: [PATCH 43/45] initial commit --- docs/asset_db/triples.md | 122 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/asset_db/triples.md diff --git a/docs/asset_db/triples.md b/docs/asset_db/triples.md new file mode 100644 index 0000000..de7d972 --- /dev/null +++ b/docs/asset_db/triples.md @@ -0,0 +1,122 @@ +# Triples Query Language + +The **Triples Query Language** allows users of the OWASP Amass framework to request data from the Asset Database using the **OWASP Open Asset Model**. This query language enables traversals across the data graph, where each triple describes a directed edge between two nodes. + +A **triple** is a traversal path that describes a step in a graph walk. Each triple consists of a **subject**, a **predicate**, and an **object**. The subject is the node being queried, the predicate describes the relationship, and the object is the target node. Results from the previous triple can serve as subjects for subsequent triples, enabling complex queries across the graph. + +## Syntax Overview + +A single **triple** follows the format for outgoing relations from the subject: + +``` + - -> +``` + +Or, the arrow pointing in the other direction for incoming relations to the subject: + +``` + <- - +``` + +- **Subject**: The starting node of the traversal. +- **Predicate**: Describes the relationship. +- **Object**: The ending node of the traversal. + +### Components of a Triple + +Each node and predicate in the triple has the following format: + +``` + + + +``` + +Here is an example of + +- **type**: The type of the node (e.g., `fqdn` or `ipaddress`). +- **label**: The specific value associated with the node (e.g. `dns_record`). +- **since**: An optional filter specifying a date to limit results after a certain point. +- **prop**: Optional properties for the node, such as additional attributes or metadata. +- **attributes**: Optional fields from the data type used for filtering (e.g. `header.rr_type:#/1|28/#`). + +### Supported Query Elements + +- **Constant Values**: Specific, static values for filtering (e.g., `fqdn:owasp.org`). +- **Wildcard ('*')**: A wildcard character that can match any value (e.g., `ipaddress:*`). +- **Regular Expressions ('#//#')**: A regular expression for more specific filtering (e.g. `#/.*google.*/#`). + +## Example Queries + +### 1. From Root Domain Name to IP Addresses + +This query retrieves all IP addresses associated with the root domain name `owasp.org`, starting from the domain and considering DNS records since July 1st, 2025. + +``` + - <*:dns_record,since:2025-07-01> -> +``` + +- **Subject**: `` +- **Predicate**: `<*:dns_record,since:2025-07-01>` +- **Object**: `` + +### 2. Root Domain Name to Subdomains + +This query retrieves all subdomains of the root domain `owasp.org`, starting from the domain and considering the relationship to nodes since July 1st, 2025. + +``` + - <*:node,since:2025-07-01> -> <*> +``` + +- **Subject**: `` +- **Predicate**: `<*:node,since:2025-07-01>` +- **Object**: `<*>` + +The object can simply specify the wildcard character, since the 'node' relation outcoming from an FQDN must connect with another FQDN. + +### 3. Subdomain to IP Address + +This query retrieves IP addresses for all subdomain names (e.g. `subdomain.owasp.org`), acquired from a previous triple, and their DNS records since July 1st, 2025. + +``` + - <*:dns_record,since:2025-07-01> -> +``` + +- **Subject**: `` +- **Predicate**: `<*:dns_record,since:2025-07-01>` +- **Object**: `` + +## Filtering with Regular Expressions + +You can use regular expressions to filter the query results. For example, if you want to query IP addresses associated with domain names that match a specific pattern, you can use: + +``` + - <*:dns_record> -> +``` + +- **Subject**: `` +- **Predicate**: `<*:dns_record>` +- **Object**: `` + +This query retrieves IP addresses for `google.com` where the IP address matches the `192.168.*` range. + +## Traversing Multiple Steps + +Triples allow for multiple traversals in a query. You can chain multiple triples to traverse from one node to another through various relationships. For example: + +``` +amass assoc -t1 ' - <*:node> -> <*>' -t2 ' - <*:dns_record> -> ' +``` + +Here, the first triple retrieves all nodes related to the root domain `owasp.org`, and the second triple retrieves IP addresses associated with those nodes. The entire walk that traverses all triples, and all related properties, is provided in the JSON output. + +## Conclusion + +The **Triples Query Language** is a powerful way to interact with the OWASP Asset Database and extract relevant data from the Open Asset Model. By using this language, users can perform flexible, precise queries to navigate the complex relationships between assets, making it a valuable tool for asset discovery and attack surface management. + +## See Also + +* [Asset Database](./index.md) +* [Setting Up PostgreSQL](./postgres.md) +* [PostgreSQL `pg_trgm` Extension Docs](https://www.postgresql.org/docs/current/pgtrgm.html) +* [Managing Environment Variables Securely](https://direnv.net/) From 093342b61249387cf15a02f368f138cea2682633 Mon Sep 17 00:00:00 2001 From: caffix Date: Thu, 31 Jul 2025 10:04:38 -0400 Subject: [PATCH 44/45] updated --- docs/asset_db/triples.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/asset_db/triples.md b/docs/asset_db/triples.md index de7d972..edc38e4 100644 --- a/docs/asset_db/triples.md +++ b/docs/asset_db/triples.md @@ -1,8 +1,8 @@ # Triples Query Language -The **Triples Query Language** allows users of the OWASP Amass framework to request data from the Asset Database using the **OWASP Open Asset Model**. This query language enables traversals across the data graph, where each triple describes a directed edge between two nodes. +The **Triples Query Language** allows users of the OWASP Amass framework to request data from the Asset Database using the **OWASP Open Asset Model**. This query language enables traversals across the graph, where each triple describes a directed edge between two nodes. -A **triple** is a traversal path that describes a step in a graph walk. Each triple consists of a **subject**, a **predicate**, and an **object**. The subject is the node being queried, the predicate describes the relationship, and the object is the target node. Results from the previous triple can serve as subjects for subsequent triples, enabling complex queries across the graph. +A **triple** is a traversal path that describes a step in a graph walk, or a "hop" in your graph between two nodes. Each triple consists of a **subject**, a **predicate**, and an **object**. The subject is the node being queried, the predicate describes the relationship, and the object is the target node. Results from the previous triple can serve as subjects for subsequent triples, enabling complex queries across the graph. ## Syntax Overview @@ -118,5 +118,3 @@ The **Triples Query Language** is a powerful way to interact with the OWASP Asse * [Asset Database](./index.md) * [Setting Up PostgreSQL](./postgres.md) -* [PostgreSQL `pg_trgm` Extension Docs](https://www.postgresql.org/docs/current/pgtrgm.html) -* [Managing Environment Variables Securely](https://direnv.net/) From 6ce0b3f767d964236823b8053c069cbb2aa3d5e8 Mon Sep 17 00:00:00 2001 From: 51nk0r5w1m <51nk0r5w1m> Date: Fri, 1 Aug 2025 15:39:33 -0400 Subject: [PATCH 45/45] Updated AssetDB index.md --- docs/asset_db/index.md | 209 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) diff --git a/docs/asset_db/index.md b/docs/asset_db/index.md index e69de29..ed1dfdf 100644 --- a/docs/asset_db/index.md +++ b/docs/asset_db/index.md @@ -0,0 +1,209 @@ +# :simple-owasp: Asset Database + +The **Asset DB** is the **PostgreSQL implementation** of the database layer for the OWASP Amass framework. It provides a robust database interaction layer for storing and managing the [Open Asset Model (OAM)](https://github.com/owasp-amass/open-asset-model). While Amass supports multiple database backends (including Neo4j/Bolt , SQLite), the Asset Database specifically implements the PostgreSQL storage layer with optimized schema and query capabilities. + +--- + +## // Overview + +The [Asset Database](https://github.com/owasp-amass/asset-db) is designed to facilitate an ecosystem of scanning tools, allowing the storage of assets and their complex relationships in a structured, queryable format. This enables: + +- **Persistent Asset Intel**: Store discovered assets and their relationships for long-term analysis. +- **Query Complex Relationships**: Use the [Triples Query Language](triples.md) to traverse asset relationships. +- **Track Asset Evolution**: Monitor changes in your attack surface over time. +- **Interoperability**: Provide a unified data layer for security tools. + +!!! info "Open Asset Model Integration" + The Asset Database is built around the [Open Asset Model](https://github.com/owasp-amass/open-asset-model), which defines standardized asset types, properties, and relationships. This ensures consistency across different tools and enables comprehensive attack surface mapping beyond just internet infrastructure. + +--- + +## // Key Features + +#### :octicons-database-16: Graph Database: + +- **PostgreSQL Backend**: Optimized schema and extensions for PostgreSQL. +- **Graph-based Storage**: Leverages PostgreSQL's graph capabilities for relationship queries. +- **Scalable Architecture**: Designed for enterprise environments with large asset inventories. +- **Triples Query Language**: Advanced graph traversal language built for PostgreSQL. + +#### :octicons-graph-16: Complex Mapping: + +- **Asset Relationships**: Store and query complex relationships between different asset types. +- **Triples Query Language**: Powerful graph traversal language for complex queries. +- **Multi-triple Traversals**: Support for up to 10 triples for complex graph walks. +- **Temporal Tracking**: Track when relationships were discovered and their confidence levels. +- **Attribute Filtering**: Filter results by asset and relation attributes. + +#### :octicons-tools-16: System Integration: + +- **Command Line Interface**: Subcommand querying via `amass assoc`. +- **Database Interface**: Direct database access for programmatic integration. +- **Modular Architecture**: Extensible design supporting custom integrations. +- **Export Capabilities**: Export data in multiple formats for analysis and reporting. + +--- + +## // Supported Asset Types + +The Asset Database supports all asset types defined in the [Open Asset Model](../open_asset_model/index.md). For detailed information about each asset type, see [Assets](../open_asset_model/assets/index.md). + +--- + +## //Architecture + + +The Asset Database follows a **layered architecture pattern** that provides exceptional flexibility, scalability, and maintainability. This design pattern separates concerns into distinct layers, each with specific responsibilities and clear interfaces between them. + +--- + +```mermaid +graph LR + subgraph "Client Layer" + direction TB + A["Amass Core"] + B["Data Sources"] + C["Go Library"] + end + + subgraph "Repository Layer" + direction TB + D["Asset Storage"] + E["Relationship Mgmt"] + F["Query Interface"] + end + + subgraph "Database Layer" + direction TB + G[(PostgreSQL)] + H["Schema Mgmt"] + I["pg_trgm Extension"] + end + + %% Flows + A --> D + B --> D + C --> D + D --> E + E --> F + F --> G + G --> H + G --> I +``` +--- + +#### :material-console: **Client Layer** >> Interface & Integration + +> This layer handles user interactions and data ingestion: + +- **Amass Core**: Primary enumeration engine and discovery framework. + +- **Data Sources**: External feeds and tools that populate the database. + +- **Go Library**: Programmatic access for custom integrations and automation. + +#### :material-spider-web: **Repository Layer** >> Data Abstraction & Logic + +> This layer implements the core data operations and query logic: + +- **Asset Storage**: CRUD operations for all asset types (FQDNs, IPs, Organizations, etc.). + +- **Relationship Management**: Graph relationship storage and traversal logic. + +- **Query Interface**: Triples Query Language implementation and query processing. + +- **Abstraction**: Provides a consistent entry point for data operations and removed underlying database complexity. + +#### :material-table-column: **Database Layer** >> Data Persistence & Storage + +> This layer handles data persistence and optimization: + + - **PostgreSQL**: Primary database with optimized schema for graph relationships. + + - **Schema Management**: Table structures and indexing for efficient queries. + + - **`pg_trgm`**: Trigram indexing for fuzzy string matching and search. + +--- + +#### Why This Works Well: + +**>> Separation of Concerns** + +>Each layer has a specific responsibility: + +- **Client Layer**: User interface and data ingestion + +- **Repository Layer**: Data abstraction and business logic + +- **Database Layer**: Data persistence and storage + +> This separation enables independent development and testing. + +#### **>> Multiple Integration Patterns** +>The system supports various access methods: + +- **Command Line**: Direct querying via `amass assoc` command + +- **Go Library**: Programmatic access for custom applications + +- **Database**: Direct SQL access for advanced analytics + +#### **>> Database Flexibility** +>The Repository Layer abstracts database details, enabling: + +- **PostgreSQL**: Primary implementation with graph capabilities. + +- **Neo4j**: Graph database for complex relationships + +- **SQLite**: Lightweight option for basic deployments + +#### **>> Modular Design** + +>The layered architecture provides: + +- **Independent Development**: Teams can work on different layers +- **Clear Interfaces**: Well-defined boundaries between components +- **Extensible Structure**: Easy to add new features or modify existing ones + +#### **>> Maintainability** +>Clear layer boundaries enable: + +- **Isolated Testing**: Each layer can be tested independently +- **Problem Isolation**: Issues can be traced to specific layers +- **Independent Updates**: Changes in one layer don't affect others + +--- + +This design means you can: + +- **Start Simple**: Begin with basic enumeration and add more later +- **Grow When Needed**: Add more data sources as you need them +- **Use Your Tools**: Work with your existing security setup +- **Build Your Own**: Create custom tools if you want to +- **Keep It Working**: Make changes without breaking everything + +--- + +## // Common Use Cases + +#### >> Security Research: + +- **Find Assets**: Discover domains, IPs, and other assets you didn't know about +- **Track Changes**: See what's new or changed in your target's infrastructure +- **Map Relationships**: Understand how different assets connect to each other + +#### >> Bug Bounty & Penetration Testing: + +- **Scope Discovery**: Find all the assets in your target's attack surface +- **Asset Tracking**: Keep track of what you've found during your research +- **Relationship Mapping**: See how assets relate to each other for better targeting + +#### >> Security Analysis: + +- **Asset Inventory**: Build a complete picture of what you're analyzing +- **Historical Tracking**: See what assets were discovered when +- **Data Export**: Get your findings out for further analysis +``` + +