# Assets Management

Assets represent the applications, services, and infrastructure components in your security testing inventory. The Escape CLI provides comprehensive asset management capabilities for tracking and organizing your security surface.

## Understanding Assets

Assets in Escape fall into several categories:

- **API Services** - REST APIs, GraphQL APIs
- **Web Applications** - Browser-based applications
- **Hosts** - DNS entries, IP addresses
- **Schemas** - OpenAPI specifications, GraphQL schemas

Assets serve as the foundation for security testing profiles. Before you can create a profile and run scans, you need to define the corresponding assets.

## Listing Assets

View all assets in your organization's inventory.

### Basic Usage

```bash
escape-cli assets list
```

**Aliases:** `list`, `ls`

**Table Columns:** `ID`, `CREATED AT`, `TYPE`, `STATUS`, `LAST SEEN`, `RISKS`, `TAGS`, `OWNERS`, `PROJECTS`, `NAME`.

### Filtering Assets

Narrow your asset list using filters:

```bash
# Filter by manually created assets
escape-cli assets list --manually-created

# Search by name or URL
escape-cli assets list --search "example.com"

# Filter by status
escape-cli assets list --statuses MONITORED,OUT_OF_SCOPE

# Filter by asset type
escape-cli assets list --types REST_FASTAPI,REST_DJANGO

# Filter by project
escape-cli assets list --project-id 11111111-1111-1111-1111-111111111111

# Combine filters
escape-cli assets list --types REST_FASTAPI --statuses MONITORED
```

**Available filters:**

| Flag | Description | Values |
| --- | --- | --- |
| `-m, --manually-created` | Only manually created assets | \- |
| `--project-id` | Filter by project IDs | Comma-separated UUIDs |
| `-s, --search` | Search by name, URL, or domain | Any string |
| `--statuses` | Filter by status | `DEPRECATED`, `FALSE_POSITIVE`, `MONITORED`, `OUT_OF_SCOPE`, `THIRD_PARTY` |
| `-t, --types` | Filter by technology type | See [Asset Types](<#asset-types>) below |
| `--sort-by` | Sort field | For example, `LAST_SEEN`, `CREATED_AT` |
| `--sort-direction` | Sort direction | `asc`, `desc` |

### Asset Types

**Frontend Technologies:**

- `FRONTEND_ANGULAR`
- `FRONTEND_DJANGO`
- `FRONTEND_JAVASCRIPT`
- `FRONTEND_JQUERY`
- `FRONTEND_REACT`
- `FRONTEND_SVELTE`
- `FRONTEND_VUE`

**GraphQL Frameworks:**

- `GRAPHQL_APOLLO`
- `GRAPHQL_GRAPHQLYOGA`

**REST API Frameworks:**

- `REST_ASP_NET`
- `REST_CLOJURE`
- `REST_DJANGO`
- `REST_EXPRESS_JS`
- `REST_FASTAPI`
- `REST_FLASK`
- `REST_GIN`
- `REST_HONO`
- `REST_LARAVEL`
- `REST_NESTJS`
- `REST_NEXTJS`
- `REST_NUXTJS`
- `REST_RUBY_ON_RAILS`
- `REST_SCALA_PLAY`
- `REST_SPRING_BOOT`
- `REST_SYMFONY` **Unclassified:** `UNKNOWN`

**API Reference:** [GET /assets](<https://public.escape.tech/v3/#tag/assets/get/assets>)

## Getting Asset Details

Retrieve detailed information about a specific asset.

```bash
escape-cli assets get <asset-id>
```

**Aliases:** `get`, `g`

**Example:**

```bash
escape-cli assets get 11111111-1111-1111-1111-111111111111
```

**Table Columns:** `ID`, `CREATED AT`, `TYPE`, `STATUS`, `LAST SEEN`, `RISKS`, `TAGS`, `OWNERS`, `PROJECTS`, `NAME`.

**API Reference:** [GET /assets/{id}](<https://public.escape.tech/v3/#tag/assets/get/assets/%7BassetId%7D>)

## Creating Assets

Add new assets to your security testing inventory. The creation process varies by asset type.

### REST API Service

Create an asset for a REST API service:

```bash
cat <<EOF | escape-cli asset create
{
  "asset_class": "API_SERVICE",
  "asset_type": "REST",
  "url": "https://api.example.com"
}
EOF
```

Or from a file:

```bash
escape-cli asset create < rest-asset.json
```

**Configuration structure:**

```json
{
  "asset_class": "API_SERVICE",
  "asset_type": "REST",
  "url": "https://api.example.com",
  "framework": "REST_FASTAPI",
  "description": "Production REST API for user management"
}
```

### GraphQL API Service

```bash
cat <<EOF | escape-cli asset create
{
  "asset_class": "API_SERVICE",
  "asset_type": "GRAPHQL",
  "url": "https://api.example.com/graphql"
}
EOF
```

### Web Application

```bash
cat <<EOF | escape-cli asset create
{
  "asset_class": "WEB_APPLICATION",
  "asset_type": "WEBAPP",
  "url": "https://app.example.com"
}
EOF
```

### DNS Host

```bash
cat <<EOF | escape-cli asset create
{
  "asset_class": "HOST",
  "asset_type": "DNS",
  "address": "example.com"
}
EOF
```

### Schema Asset

Schema assets store API specifications:

```bash
# First, upload the schema
UPLOAD_ID=$(escape-cli upload schema -o json < openapi.json | jq -r '.')

# Create the schema asset
cat <<EOF | escape-cli asset create
{
  "asset_type": "SCHEMA",
  "upload": {
    "temporaryObjectKey": "$UPLOAD_ID"
  }
}
EOF
```

**API Reference:** [POST /assets](<https://public.escape.tech/v3/#tag/assets/post/assets>)

## Updating Assets

Modify existing asset properties.

```bash
escape-cli assets update <asset-id> [flags]
```

**Aliases:** `update`, `u`

### Update Examples

```bash
# Update asset status
escape-cli assets update <asset-id> --status MONITORED

# Update framework detection
escape-cli assets update <asset-id> --framework REST_FASTAPI

# Update description
escape-cli assets update <asset-id> --description "Production user authentication API"

# Assign owners
escape-cli assets update <asset-id> --owners user1@example.com,user2@example.com

# Assign tags
escape-cli assets update <asset-id> --tag-ids <tag-id-1>,<tag-id-2>

# Combine multiple updates
escape-cli assets update <asset-id> \
  --status MONITORED \
  --framework REST_FASTAPI \
  --description "Updated description"
```

**Available flags:**

| Flag | Description | Values |
| --- | --- | --- |
| `-d, --description` | Asset description | Any string |
| `-f, --framework` | Technology framework | See [Asset Types](<#asset-types>) |
| `--owners` | Asset owner emails | Comma-separated emails |
| `-s, --status` | Asset status | `DEPRECATED`, `FALSE_POSITIVE`, `MONITORED`, `OUT_OF_SCOPE`, `THIRD_PARTY` |
| `-t, --tag-ids` | Tag IDs | Comma-separated UUIDs |

**API Reference:** [PUT /assets/{id}](<https://public.escape.tech/v3/#tag/assets/put/assets/%7BassetId%7D>)

## Deleting Assets

Remove assets from your inventory.

```bash
escape-cli assets delete <asset-id>
```

**Aliases:** `delete`, `d`

**Example:**

```bash
escape-cli assets delete 11111111-1111-1111-1111-111111111111
```

> [!WARNING]
>
> **Deletion is Permanent**
>
> Export any data you need before deleting an asset. This action can't be undone.

**API Reference:** [DELETE /assets/{id}](<https://public.escape.tech/v3/#tag/assets/delete/assets/%7BassetId%7D>)

## Comments and Activity

```bash
escape-cli assets comment <asset-id> --message "Review requested"
escape-cli assets list-activities <asset-id>
escape-cli assets get <asset-id> --activities
```

`comment` requires `--message` (up to 512 characters). `list-activities` has the alias `activities`. `get --activities` (short form `-a`) shows issue activities associated with the asset.

## Bulk Asset Operations

`assets bulk-update` updates matching assets' tags, projects, or status. Filter with `--asset-id`, `--type`, or `--asset-status`; set values with `--tag-id`, `--project-id`, or `--status`.

```bash
escape-cli assets bulk-update --asset-id <asset-id-1>,<asset-id-2> --status OUT_OF_SCOPE
```

`assets bulk-delete` schedules matching assets for deletion. It accepts the same `--asset-id`, `--type`, and `--asset-status` filters. Inspect the matching assets before running it.

### Importing Multiple Assets

Import assets from a file with one asset per line:

```bash
# Create assets from a list of URLs
while read -r url; do
cat <<EOF | escape-cli asset create
{
  "asset_class": "API_SERVICE",
  "asset_type": "REST",
  "url": "$url"
}
EOF
done < urls.txt
```

### Importing from CSV

Parse structured data and create assets:

```bash
# CSV format: date,domain,comment
# Example: 2025-01-01,example.com,Production domain

sed 1d assets.csv | while IFS=',' read -r date domain comment; do
cat <<EOF | escape-cli asset create
{
  "asset_class": "HOST",
  "asset_type": "DNS",
  "address": "$domain"
}
EOF
done
```

### Importing from JSON

Process JSON arrays of assets:

```bash
# Read JSON array and create each asset
jq -c '.[]' assets.json | while read -r asset; do
  echo "$asset" | escape-cli asset create
done
```

## Asset Status Management

Asset statuses help organize and prioritize your inventory:

### Status Meanings

| Status | Description | Use Case |
| --- | --- | --- |
| `MONITORED` | Actively tracked and tested | Production assets requiring continuous monitoring |
| `OUT_OF_SCOPE` | Not included in testing | Third-party services, deprecated features |
| `DEPRECATED` | Marked for removal | Legacy systems being phased out |
| `FALSE_POSITIVE` | Incorrectly identified | Assets discovered by ASM that aren't actually yours |
| `THIRD_PARTY` | Third-party service | External services displayed but not scanned |

### Updating Status

```bash
# Mark an asset as actively monitored
escape-cli assets update <asset-id> --status MONITORED

# Mark as out of scope
escape-cli assets update <asset-id> --status OUT_OF_SCOPE

# Mark as deprecated
escape-cli assets update <asset-id> --status DEPRECATED

# Mark as false positive
escape-cli assets update <asset-id> --status FALSE_POSITIVE
```

## Asset Organization

### Using Tags

Tags enable flexible asset categorization:

```bash
# Create tags for organization
PROD_TAG=$(escape-cli tags create --name production --color e03d3d -o json | jq -r '.id')
CRITICAL_TAG=$(escape-cli tags create --name critical --color ff0000 -o json | jq -r '.id')

# Apply tags to assets
escape-cli assets update <asset-id> --tag-ids $PROD_TAG,$CRITICAL_TAG
```

### Assigning Owners

Track asset ownership for accountability:

```bash
# Assign single owner
escape-cli assets update <asset-id> --owners security-team@example.com

# Assign multiple owners
escape-cli assets update <asset-id> --owners \
  security@example.com,devops@example.com
```

### Adding Descriptions

Document asset context and purpose:

```bash
escape-cli assets update <asset-id> \
  --description "User authentication API - Handles OAuth2 flows and JWT tokens"
```

## Best Practices

### Asset Discovery Strategy

1. **Start with known inventory** - Manually create assets for your critical applications
2. **Enable ASM** - Let Attack Surface Management discover additional assets
3. **Review and classify** - Regularly review discovered assets and update their status
4. **Tag strategically** - Use tags to group assets by team, environment, or criticality

### Naming and Documentation

- **Use descriptive names** - Include service purpose and environment
- **Add comprehensive descriptions** - Document what the asset does and why it matters
- **Track ownership** - Assign clear owners for each asset
- **Update regularly** - Keep asset information current as systems evolve

### Security Hygiene

- **Mark deprecated assets** - Track systems being phased out
- **Scope testing appropriately** - Exclude third-party or out-of-scope assets
- **Regular audits** - Periodically review your asset inventory for accuracy
- **Framework detection** - Update technology frameworks for accurate testing

## Troubleshooting

### Asset Creation Fails

**Issue**: "Invalid URL format"

- Ensure the URL includes the protocol (`https://` or `http://`)
- Verify the URL is accessible and properly formatted

**Issue**: "Duplicate asset"

- Check if an asset with the same URL or address already exists
- Use `escape-cli assets list --search "example.com"` to find duplicates

### Asset Not Found After Creation

If you created an asset but can't find it:

- Use JSON output to capture the asset ID: `escape-cli asset create -o json < asset.json`
- Search by URL or domain: `escape-cli assets list --search "example.com"`

### Permission Errors

If you can't create or modify assets:

- Verify your API key has the required permissions
- Contact your organization administrator to grant asset management permissions

## Next Steps

- **[Profiles Management](<https://docs.escape.tech/documentation/automate/cli/profiles/index.md>)** - Create security testing profiles for your assets
- **[Scans Management](<https://docs.escape.tech/documentation/automate/cli/scans/index.md>)** - Run security scans against your assets
- **[Practical Recipes](<https://docs.escape.tech/documentation/automate/cli/recipes/index.md>)** - Complete asset management examples