Skip to content

Commit 0a7e851

Browse files
caffixcaffix
committed
updates
1 parent 1ecbd0e commit 0a7e851

26 files changed

+544
-187
lines changed

‎docs/open_asset_model/assets/account.md‎

Lines changed: 60 additions & 185 deletions
Original file line numberDiff line numberDiff line change
@@ -1,211 +1,86 @@
1-
# :simple-owasp: `Account`
1+
# :simple-owasp: Account
22

3-
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.
3+
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.
44

5-
## Table of Contents
5+
Each `Account` asset includes structured metadata describing its identity and lifecycle:
66

7-
- [Overview](#overview)
8-
- [Account Structure](#account-structure)
9-
- [Attributes](#attributes)
10-
- [Implemented Interfaces and Methods](#implemented-interfaces-and-methods)
11-
- [Key()](#key)
12-
- [AssetType()](#assettype)
13-
- [JSON()](#json)
14-
- [Relationship with the Open Asset Model](#relationship-with-the-open-asset-model)
15-
- [Usage](#usage)
7+
- **ID** – A globally unique identifier for the account within the graph.
8+
- **Type** – The kind of account represented (e.g., `email`, `bank`, `cloud`, `user`, `subscription`).
9+
- **Username** – The login handle, screen name, or identifier tied to the account (e.g., `admin@corp.com`, `acme-billing`).
10+
- **Account Number** – An optional unique number assigned to the account (e.g., bank account or customer ID).
11+
- **Balance** – Optional numeric value representing a monetary balance or credit (used primarily for financial contexts).
12+
- **Active** – A boolean indicating whether the account is currently in use or retired.
1613

17-
---
18-
19-
## **//** Overview
20-
21-
The **Account asset** is an integral part of the **Open Asset Model**, designed to support:
22-
23-
- **Financial & entity-managed accounts** (e.g., bank, corporate, or payment accounts).
24-
25-
- **Multiple relationships** such as **entity ownership (Person/Organization)** and **fund transfers**.
26-
27-
- **Standardized data structure** for integration with external financial and asset-tracking systems.
28-
29-
The **`Account`** struct is designed with **JSON tags for serialization**, ensuring seamless integration with **APIs and structured storage systems**.
30-
31-
---
32-
33-
## **//** Account Structure
34-
35-
The **`Account`** struct defines key attributes necessary for financial asset representation.
36-
37-
```go
38-
// Account represents an account managed by an organization.
39-
type Account struct {
40-
ID string `json:"unique_id"` // Unique identifier
41-
Type string `json:"account_type"` // Type of account (e.g., savings, checking)
42-
Username string `json:"username,omitempty"` // Optional username
43-
Number string `json:"account_number,omitempty"` // Account number
44-
Balance float64 `json:"balance,omitempty"` // Account balance
45-
Active bool `json:"active,omitempty"` // Status of the account
46-
}
47-
```
48-
49-
---
50-
51-
**Attribute Breakdown**
52-
53-
| **Field Name** | **Type** | **JSON Tag** | **Description** |
54-
|----------------|-----------|------------------------------|--------------------------------------------------------------------------|
55-
| **`ID`** | `string` | `"unique_id"` | **Unique identifier** for the account (used as the **asset key**) |
56-
| **`Type`** | `string` | `"account_type"` | Represents the **type of account** (e.g., savings, checking) |
57-
| **`Username`** | `string` | `"username,omitempty"` | Optional **username** associated with the account |
58-
| **`Number`** | `string` | `"account_number,omitempty"` | Optional **account number** used as a secondary identifier |
59-
| **`Balance`** | `float64` | `"balance,omitempty"` | Represents the **current balance** of the account |
60-
| **`Active`** | `bool` | `"active,omitempty"` | Indicates whether the **account is active** |
61-
62-
---
63-
64-
!!! info " omitempty "
65-
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.
66-
67-
---
68-
69-
## **//** Implemented Interfaces and Methods
70-
71-
The **`Account` struct** implements the **Asset interface**, ensuring consistency across the **Open Asset Model**.
72-
73-
### `Key()`
74-
75-
- **Purpose:**
76-
Returns a unique key (identifier) for the asset. This key is fundamental for distinguishing between different assets.
77-
78-
- **Implementation:**
79-
80-
```go
81-
// Key implements the Asset interface.
82-
func (a Account) Key() string {
83-
return a.ID
84-
}
85-
```
86-
**Usage:**
87-
88-
- Used to **uniquely identify** the account.
14+
- **Definition:** *An identity-linked asset that represents a digital, user, or financial account used to access or control resources across infrastructure or service environments.*
8915

90-
- Serves as the **primary key** for asset indexing and retrieval.
16+
- **Purpose:** The Account asset plays a vital role in representing non-infrastructure access points—especially those tied to identity, privilege, and control.
9117

92-
---
93-
94-
### `AssetType()`
95-
96-
- **Purpose:**
97-
Returns the specific type of the asset within the **Open Asset Model**.
98-
99-
- **Implementation:**
18+
Key use cases include:
10019

101-
```go
102-
// AssetType implements the Asset interface.
103-
func (a Account) AssetType() model.AssetType {
104-
return model.Account
105-
}
106-
```
107-
**Usage:**
20+
- **Credential Discovery** – Modeling usernames or accounts found in source code, breach data, or service responses.
21+
- **Privilege Mapping** – Associating accounts with specific services or roles in cloud or SaaS environments.
22+
- **Exposure Attribution** – Tracing exposed keys, billing accounts, or cloud identities back to organizations.
23+
- **Operational Monitoring** – Tracking stale or inactive accounts that may indicate shadow IT or abandoned assets.
24+
- **Financial Context** – Enriching infrastructure or access graphs with business-relevant metadata like balances or customer IDs.
10825

109-
- Allows systems to **categorize the asset** as an **`Account`**.
26+
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.
11027

111-
- Ensures **type consistency** when processing different asset categories.
28+
- **Design Choice:** The design of the Account asset type is intentionally minimal, yet extensible:
11229

113-
---
114-
115-
### `JSON()`
30+
- **Type-Driven Classification** – The account_type field enables generalized modeling (e.g., cloud, user, bank) while allowing tooling to define additional specificity as needed.
31+
- **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).
32+
- **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).
33+
- **Lifecycle Awareness** – The active boolean enables visibility into the operational state of the account, useful for spotting dormant, disabled, or legacy identities.
11634

117-
- **Purpose:**
118-
Serializes the **`Account`** struct into **JSON format** for **data exchange and storage**.
35+
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.
11936

120-
- **Implementation:**
37+
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.
12138

122-
```go
123-
// JSON implements the Asset interface.
124-
func (a Account) JSON() ([]byte, error) {
125-
return json.Marshal(a)
126-
}
127-
```
39+
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.
12840

129-
**Usage:**
41+
## :material-account: Account Attributes
13042

131-
- Converts the asset into **JSON format** for **APIs, databases, and logging**.
43+
| Attributes | Type | Required. | Description. |
44+
| :-------------------: | :---------: | :----------: | :------------- |
45+
| `unique_id` | string | :material-check-decagram: | Unique identifier for the account within the model |
46+
| `account_type` | string | :material-check-decagram: | Classification of the account (e.g., `cloud`, `bank`, `user`) |
47+
| `username` | string | :material-checkbox-blank-circle-outline: | Login name, email, or screen name associated with the account |
48+
| `account_number` | string | :material-checkbox-blank-circle-outline: | Optional numeric or alphanumeric account ID (e.g., `acct-1234`) |
49+
| `balance` | float | :material-checkbox-blank-circle-outline: | Optional financial or credit balance |
50+
| `active` | boolean | :material-checkbox-blank-circle-outline: | Whether the account is currently active |
13251

133-
- Enables **data transmission** across services.
134-
135-
---
52+
## :material-account: Account Properties
13653

137-
## **//** Relationship with the Open Asset Model
138-
139-
The **Open Asset Model** provides a standardized approach to handling digital and physical assets. The **`Account`** asset is a critical component and supports:
140-
141-
- **User Entities**: Representing **Persons or Organizations** that own the account.
142-
143-
- **Funds Transfers**: Tracking **financial transactions** between accounts.
144-
145-
- **Banking Identifiers**: Supporting **IBAN and SWIFT codes** for financial integration.
146-
147-
By adhering to these relationships, the **`Account model`** ensures structured data exchange between **security, financial, and asset management systems**.
148-
149-
---
54+
| Property Type | Property Name | Description |
55+
| :-----------------: | :-----------------: | :------------ |
56+
| [`SimpleProperty`](../properties/simple_property.md) | `last_monitored` | Tracks when a data source was last queried regarding this Account |
57+
| [`SourceProperty`](../properties/source_property.md) | Source Plugin Name | Indicates that the specified data source discovered this Account |
15058

151-
## **//** Usage
59+
## :material-account: Account Outgoing Relations
15260

153-
The **Open Asset Model** provides structured asset management for accounts.
61+
```mermaid
62+
graph TD
63+
acct["Account"]
64+
ident["Identifier"]
65+
idRel@{ shape: braces, label: "id"}
66+
acct --o idRel
67+
idRel --> ident
15468
155-
Below is an example demonstrating how to:
156-
157-
- **Retrieve account details**.
158-
159-
- **Serialize an account to JSON**.
160-
161-
```go
162-
package main
163-
164-
import (
165-
"encoding/json"
166-
"fmt"
167-
"github.com/owasp-amass/open-asset-model/account"
168-
)
169-
170-
func main() {
171-
// Define an example account asset
172-
acc := account.Account{
173-
ID: "acc-12345",
174-
Type: "Savings",
175-
Username: "johndoe",
176-
Number: "987654321",
177-
Balance: 1500.75,
178-
Active: true,
179-
}
180-
181-
// Serialize the account to JSON
182-
jsonData, err := acc.JSON()
183-
if err != nil {
184-
fmt.Println("Error serializing account to JSON:", err)
185-
return
186-
}
187-
188-
fmt.Printf("Account Type: %s\n", acc.Type)
189-
fmt.Printf("Serialized JSON: %s\n", string(jsonData))
190-
}
69+
org["Organization"]
70+
person["Person]
71+
user@{ shape: braces, label: "user"}
72+
acct --o user
73+
user --> org
74+
user --> persom
19175
```
19276

19377
---
19478

195-
## **//** Summary
79+
| Relation Type | Relation Label | Target Assets | Description |
80+
| :-----------------: | :----------------: | :---------------: | :------------ |
81+
| [`SimpleRelation`](../relations/simple_relation.md) | `id` | [`Identifier`](./identifier.md) | Links the account to other discovered identifiers |
82+
| [`SimpleRelation`](../relations/simple_relation.md) | `user` | [`Organization`](./organization.md), [`Person`](./person.md) | Links the account to known users that have access |
19683

197-
The **`account.go`** file is a fundamental part of the **Open Asset Model**, ensuring structured and standardized management of **financial and user-managed accounts**.
198-
199-
Key takeaways:
200-
201-
- **Defines an `Account` struct** that represents various financial accounts.
202-
203-
- **Implements the Asset interface** to ensure consistency.
204-
205-
- Supports relationships with **user entities, financial transactions, and banking identifiers**.
206-
207-
- Provides **JSON serialization** for easy data exchange.
208-
209-
By following this structured approach, **contributors** can extend account functionality, while **users** can efficiently manage financial assets in their security and asset intelligence workflows.
84+
---
21085

211-
---
86+
*© 2025 Jeff Foley — Licensed under Apache 2.0.*

‎docs/open_asset_model/assets/autonomous_system.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,7 @@ regrel --> autnum
4545
| :-----------------: | :----------------: | :--------------: | :------------ |
4646
| [`SimpleRelation`](../relations/simple_relation.md) | `announces` | [`Netblock`](./netblock.md) | Links an IPAddress to its DNS name used in PTR records |
4747
| [`SimpleRelation`](../relations/simple_relation.md) | `registration` | [`AutnumRecord`](./autnum_record.md) | Links a ASN to its associated registration data |
48+
49+
---
50+
51+
*© 2025 Jeff Foley — Licensed under Apache 2.0.*

‎docs/open_asset_model/assets/contact_record.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,7 @@ simple6 --> url
6262
| [`SimpleRelation`](../relations/simple_relation.md) | `person` | [`Person`](#person) | Represents a person's name discovered with the contact information |
6363
| [`SimpleRelation`](../relations/simple_relation.md) | `phone` | [`Phone`](#phone) | Represents a phone number in the contact information |
6464
| [`SimpleRelation`](../relations/simple_relation.md) | `url` | [`URL`](#url) | Represents an URL discovered in the contact information |
65+
66+
---
67+
68+
*© 2025 Jeff Foley — Licensed under Apache 2.0.*

0 commit comments

Comments
 (0)