# Advanced Features

This guide covers advanced CLI features including custom rules, tags, and file uploads for extending your security testing capabilities.

## Custom Rules

Custom rules allow you to define organization-specific security checks beyond the standard OWASP and industry tests.

### Overview

Create custom rules for:

- Business logic vulnerabilities
- Company-specific security policies
- Custom compliance requirements
- API-specific security patterns

**Rule Contexts:**

- **ASM** (API Security Management) - Attack surface monitoring
- **Business Logic Aware DAST** (Dynamic Testing) - Active security testing

**Rule Severity:** CRITICAL, HIGH, MEDIUM, LOW, INFO

### Listing Custom Rules

View all custom rules in your organization.

```bash
escape-cli custom-rules list
```

**Aliases:** `ls`, `cr`, `rules`

**Example Output:**

```text
ID                                      NAME                       SEVERITY    CREATED AT            UPDATED AT
11111111-1111-1111-1111-111111111111    Custom Auth Check         HIGH        2025-10-15T10:00:00Z  2025-10-15T10:00:00Z
22222222-2222-2222-2222-222222222222    Business Logic Rule       MEDIUM      2025-10-14T15:30:00Z  2025-10-14T15:30:00Z
```

### Getting Custom Rule Details

Retrieve detailed information about a specific rule.

```bash
escape-cli custom-rules get <rule-id>
```

**Aliases:** `g`

**View rule content (`-c` is the short form):**

```bash
escape-cli custom-rules get <rule-id> --content
```

**Export rule:**

```bash
escape-cli custom-rules get <rule-id> -o json > my-rule.json
```

### Creating Custom Rules

Create a new custom rule from JSON configuration.

```bash
escape-cli custom-rules create < rule-config.json
```

**Alias:** `c`

The request wraps the definition in `content.rule`. Alert metadata, including `name`, `severity`, `context`, and `category`, belongs in `content.rule.alert`. Optional `dastEnabled`, `inventoryEnabled`, and `tagIds` fields belong at the top level.

Inspect the input schema before preparing your JSON:

```bash
escape-cli custom-rules create --input-schema
```

See the [Custom Rules reference](<https://docs.escape.tech/documentation/reference/custom-rules-reference/index.md>) for rule definitions.

### Updating Custom Rules

Modify an existing custom rule.

```bash
escape-cli custom-rules update <rule-id> < updated-rule.json
```

**Alias:** `u`

### Deleting Custom Rules

Remove a custom rule from your organization.

```bash
escape-cli custom-rules delete <rule-id>
```

**Alias:** `d`

## Tags

Tags help organize and filter assets, profiles, issues, and other resources across your organization.

### Overview

**Common Use Cases:**

- Environment labels (production, staging, development)
- Team ownership (frontend-team, backend-team, security-team)
- Criticality (critical, high-priority, low-priority)
- Compliance (pci-dss, hipaa, gdpr)
- Project grouping (project-alpha, project-beta)

### Listing Tags

View all tags in your organization.

```bash
escape-cli tags list
```

**Aliases:** `ls`, `tag`

**Example Output:**

```text
ID                                      NAME                COLOR
11111111-1111-1111-1111-111111111111    production         e03d3d
22222222-2222-2222-2222-222222222222    staging            f5a623
33333333-3333-3333-3333-333333333333    backend-team       4a90e2
```

**Export tags:**

```bash
escape-cli tags list -o json > organization-tags.json
```

### Creating Tags

Create a new tag with custom name and color.

```bash
escape-cli tags create --name <name> --color <hex-color>
```

**Aliases:** `cr`, `add`, `new`

**Color Format:** Hex color code without `#` prefix

**Examples:**

```bash
# Production tag (red)
escape-cli tags create --name production --color e03d3d

# Staging tag (yellow)
escape-cli tags create --name staging --color f5a623

# Development tag (green)
escape-cli tags create --name development --color 50c878

# Team tags (various blues)
escape-cli tags create --name backend-team --color 4a90e2
escape-cli tags create --name frontend-team --color 7b68ee
escape-cli tags create --name security-team --color 00008b

# Priority tags
escape-cli tags create --name critical --color ff0000
escape-cli tags create --name high-priority --color ff6600
escape-cli tags create --name low-priority --color cccccc

# Compliance tags
escape-cli tags create --name pci-dss --color 9370db
escape-cli tags create --name hipaa --color 8b4513
escape-cli tags create --name gdpr --color 2f4f4f
```

### Using Tags

Once created, use tag IDs to filter and organize resources:

```bash
# Filter profiles by tag
escape-cli profiles list --tag-id <tag-id>

# Filter issues by tag
escape-cli issues list --tag-id <tag-id>

# Update asset with tags
escape-cli assets update <asset-id> --tag-ids "tag-id-1,tag-id-2"
```

### Tag Organization Strategy

#### By Environment

```bash
# Create environment tags
TAG_PROD=$(escape-cli tags create --name production --color e03d3d -o json | jq -r '.id')
TAG_STAGING=$(escape-cli tags create --name staging --color f5a623 -o json | jq -r '.id')
TAG_DEV=$(escape-cli tags create --name development --color 50c878 -o json | jq -r '.id')

# Tag assets by environment
escape-cli assets update prod-api-id --tag-ids "$TAG_PROD"
escape-cli assets update staging-api-id --tag-ids "$TAG_STAGING"
```

#### By Team

```bash
# Create team tags
TAG_BACKEND=$(escape-cli tags create --name backend-team --color 4a90e2 -o json | jq -r '.id')
TAG_FRONTEND=$(escape-cli tags create --name frontend-team --color 7b68ee -o json | jq -r '.id')

# Assign ownership
escape-cli assets update api-asset-id --tag-ids "$TAG_BACKEND"
escape-cli assets update webapp-asset-id --tag-ids "$TAG_FRONTEND"
```

#### By Criticality

```bash
# Create criticality tags
TAG_CRITICAL=$(escape-cli tags create --name critical --color ff0000 -o json | jq -r '.id')
TAG_HIGH=$(escape-cli tags create --name high-priority --color ff6600 -o json | jq -r '.id')

# Mark critical assets
escape-cli assets update payment-api-id --tag-ids "$TAG_CRITICAL"
```

## File Upload

Upload large files (like API schemas) to temporary Escape storage for use in profile creation.

### Overview

**Use Cases:**

- Large OpenAPI/Swagger specifications
- GraphQL schemas
- Postman collections
- Any schema file referenced in profile creation

### Uploading Schemas

Upload an API schema file.

```bash
escape-cli upload schema < schema-file.json
```

**Aliases:** `s`

**Returns:** Upload ID for use in profile creation

**Examples:**

```bash
# Upload OpenAPI schema
escape-cli upload schema < openapi-spec.json

# Upload and capture ID
UPLOAD_ID=$(escape-cli upload schema < schema.json -o json | jq -r '.')
echo "Uploaded with ID: $UPLOAD_ID"

# Upload GraphQL schema
escape-cli upload schema < graphql-schema.graphql
```

### Using Uploaded Files

Upload JSON output is a string. Extract it with `jq -r '.'`, create a schema asset, then pass that asset's ID in `extraAssetIds`:

```bash
UPLOAD_ID=$(escape-cli upload schema -o json < openapi.json | jq -r '.')
SCHEMA_ASSET_ID=$(jq -nc --arg upload "$UPLOAD_ID" '{
  asset_type: "SCHEMA", upload: {temporaryObjectKey: $upload}
}' | escape-cli assets create -o json | jq -r '.id')

SERVICE_ASSET_ID=$(echo '{"asset_class":"API_SERVICE","asset_type":"REST","url":"https://api.example.com"}' |
  escape-cli assets create -o json | jq -r '.id')

jq -nc --arg asset "$SERVICE_ASSET_ID" --arg schema "$SCHEMA_ASSET_ID" '{
  assetId: $asset, name: "Production API", extraAssetIds: [$schema], start: false
}' | escape-cli profiles create-rest -o json
```

`assetId` and `name` are required. `extraAssetIds` attaches schema assets; an upload ID isn't a profile field. For scan configuration, use `configurationObject` for a JSON object or `configuration` for a JSON-encoded string. See [Creating Profiles](<https://docs.escape.tech/documentation/automate/cli/profiles/#creating-profiles>) for the full workflow.

### Upload Requirements

- Files are stored temporarily
- Maximum file size limits apply (check platform documentation)
- Upload IDs expire
- Use immediately after upload for profile creation

## Integration Examples

### Automated Tag Management

```bash
#!/bin/bash
# Auto-tag new assets based on naming conventions

escape-cli assets list -o json | jq -c '.[]' | while read -r asset; do
  ASSET_ID=$(echo "$asset" | jq -r '.id')
  ASSET_NAME=$(echo "$asset" | jq -r '.name')

  # Determine tags based on name
  TAGS=""

  if [[ $ASSET_NAME == *"prod"* ]]; then
    TAGS="$TAG_PROD"
  elif [[ $ASSET_NAME == *"staging"* ]]; then
    TAGS="$TAG_STAGING"
  fi

  if [[ $ASSET_NAME == *"api"* ]]; then
    TAGS="$TAGS,$TAG_API"
  fi

  if [ -n "$TAGS" ]; then
    escape-cli assets update "$ASSET_ID" --tag-ids "$TAGS"
    echo "Tagged $ASSET_NAME"
  fi
done
```

### Custom Rule Deployment

```bash
#!/bin/bash
# Deploy custom rules across environments

RULES_DIR="./custom-rules"

for rule_file in "$RULES_DIR"/*.json; do
  echo "Deploying rule: $rule_file"

  RULE_ID=$(escape-cli custom-rules create < "$rule_file" -o json | jq -r '.id')

  if [ -n "$RULE_ID" ]; then
    echo "  ✓ Deployed with ID: $RULE_ID"
  else
    echo "  ✗ Failed to deploy"
  fi
done
```

### Bulk Schema Upload

For each schema file, create a schema asset and a REST profile. Set `ASSET_ID` to the existing REST service asset's ID:

```bash
#!/bin/bash
set -euo pipefail

for schema_file in ./schemas/*.json; do
  UPLOAD_ID=$(escape-cli upload schema -o json < "$schema_file" | jq -r '.')
  SCHEMA_ASSET_ID=$(jq -nc --arg upload "$UPLOAD_ID" '{
    asset_type: "SCHEMA", upload: {temporaryObjectKey: $upload}
  }' | escape-cli assets create -o json | jq -r '.id')

  jq -nc --arg asset "$ASSET_ID" --arg schema "$SCHEMA_ASSET_ID" \
    --arg name "$(basename "$schema_file" .json) Profile" '{
      assetId: $asset, name: $name, extraAssetIds: [$schema], start: false
    }' | escape-cli profiles create-rest -o json
done
```

## Best Practices

### Custom Rules

- **Test thoroughly** before deploying to production
- **Document rules** clearly with descriptions and remediation steps
- **Version control** rule definitions
- **Review regularly** and update as threats evolve
- **Start with INFO severity** for new rules, increase after validation

### Tags

- **Establish conventions** early (naming, colors, usage)
- **Use consistently** across all resources
- **Document tag meanings** for team reference
- **Review and clean up** unused tags periodically
- **Limit tag count** to maintain clarity

### File Uploads

- **Validate files** before upload
- **Use immediately** after upload, before the upload ID expires
- **Monitor file sizes** to avoid upload failures
- **Clean up** unused uploads when possible
- **Version control** schema files for traceability

## Troubleshooting

### Custom Rules Not Applying

If custom rules aren't detected:

- Verify rule is enabled
- Check rule context matches scan type (ASM vs Business Logic Aware DAST)
- Review rule syntax and pattern
- Test rule on known vulnerable endpoint
- Check scan logs for rule execution

### Tags Not Appearing

If tags don't show up:

- Verify tag was created successfully
- Check tag ID is correct
- Ensure you have permission to view tags
- Refresh or re-query the resource

### Upload Failures

If schema upload fails:

- Check file format is valid JSON
- Verify file size is within limits
- Ensure network connectivity
- Try uploading a smaller file first
- Check API authentication

## Next Steps

- **[Profiles Management](<https://docs.escape.tech/documentation/automate/cli/profiles/index.md>)** - Create profiles with uploaded schemas
- **[Assets Management](<https://docs.escape.tech/documentation/automate/cli/assets/index.md>)** - Organize assets with tags
- **[Issues Management](<https://docs.escape.tech/documentation/automate/cli/issues/index.md>)** - Filter issues by tags
- **[Practical Recipes](<https://docs.escape.tech/documentation/automate/cli/recipes/index.md>)** - Complete workflow examples