Feat/update docs

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
+```
+
+

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:[email protected]: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/)