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
- DAST (Dynamic Testing) - Active security testing
Rule Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO
Listing Custom Rules¶
View all custom rules in your organization.
Aliases: ls
, cr
, rules
Example Output:
ID NAME SEVERITY CREATED AT UPDATED AT
00000000-0000-0000-0000-000000000001 Custom Auth Check HIGH 2025-10-15T10:00:00Z 2025-10-15T10:00:00Z
00000000-0000-0000-0000-000000000002 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.
Aliases: g
View rule content:
Export rule:
Creating Custom Rules¶
Create a new custom rule from JSON configuration.
Aliases: c
, add
, new
Example rule configuration:
{
"name": "Custom Authentication Check",
"severity": "HIGH",
"description": "Validates custom authentication requirements",
"context": "DAST",
"rule": {
"type": "detection",
"pattern": "...",
"remediation": "Implement proper authentication..."
}
}
For complete schema, see Escape V3 API Documentation.
Updating Custom Rules¶
Modify an existing custom rule.
Aliases: u
, edit
Deleting Custom Rules¶
Remove a custom rule from your organization.
Aliases: d
, rm
Custom Rule Examples¶
Business Logic Rule¶
cat > business-logic-rule.json << 'EOF'
{
"name": "Price Manipulation Check",
"severity": "CRITICAL",
"description": "Detects ability to manipulate prices in checkout flow",
"context": "DAST"
}
EOF
escape-cli custom-rules create < business-logic-rule.json
Compliance Rule¶
cat > compliance-rule.json << 'EOF'
{
"name": "PCI-DSS Compliance Check",
"severity": "HIGH",
"description": "Validates PCI-DSS requirements",
"context": "ASM"
}
EOF
escape-cli custom-rules create < compliance-rule.json
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.
Aliases: ls
, tag
Example Output:
ID NAME COLOR
00000000-0000-0000-0000-000000000001 production e03d3d
00000000-0000-0000-0000-000000000002 staging f5a623
00000000-0000-0000-0000-000000000003 backend-team 4a90e2
Export tags:
Creating Tags¶
Create a new tag with custom name and color.
Aliases: cr
, add
, new
Color Format: Hex color code without #
prefix
Examples:
# 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:
# Filter assets by tag
escape-cli assets list --tag-ids <tag-id>
# 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¶
# 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¶
# 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¶
# 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.
Aliases: s
Returns: Upload ID for use in profile creation
Examples:
# 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 '.id')
echo "Uploaded with ID: $UPLOAD_ID"
# Upload GraphQL schema
escape-cli upload schema < graphql-schema.graphql
Using Uploaded Files¶
Use the upload ID when creating profiles:
# Capture upload ID
UPLOAD_ID=$(escape-cli upload schema < large-schema.json -o json | jq -r '.id')
# Create profile referencing the upload
cat > profile-config.json << EOF
{
"name": "My API Profile",
"asset_id": "00000000-0000-0000-0000-000000000000",
"schema_upload_id": "$UPLOAD_ID",
"configuration": {
...
}
}
EOF
escape-cli profiles create-rest < profile-config.json
Complete Workflow Example¶
#!/bin/bash
# Complete workflow: Upload schema and create profile
# 1. Upload large OpenAPI spec
echo "Uploading schema..."
UPLOAD_ID=$(escape-cli upload schema < large-openapi-spec.json -o json | jq -r '.id')
if [ -z "$UPLOAD_ID" ]; then
echo "Failed to upload schema"
exit 1
fi
echo "Schema uploaded with ID: $UPLOAD_ID"
# 2. Create profile using uploaded schema
echo "Creating profile..."
cat > temp-profile.json << EOF
{
"name": "Production API",
"asset_id": "$ASSET_ID",
"schema_upload_id": "$UPLOAD_ID",
"configuration": {
"authentication": {
"type": "bearer",
"token": "$API_TOKEN"
}
}
}
EOF
PROFILE_ID=$(escape-cli profiles create-rest < temp-profile.json -o json | jq -r '.id')
rm temp-profile.json
echo "Profile created with ID: $PROFILE_ID"
# 3. Start scan
echo "Starting scan..."
escape-cli scans start "$PROFILE_ID" --watch
Upload Limitations¶
- Files are stored temporarily
- Maximum file size limits apply (check platform documentation)
- Upload IDs are valid for a limited time
- Use immediately after upload for profile creation
Integration Examples¶
Automated Tag Management¶
#!/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¶
#!/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¶
#!/bin/bash
# Upload multiple schemas and create profiles
SCHEMAS_DIR="./schemas"
for schema_file in "$SCHEMAS_DIR"/*.json; do
SCHEMA_NAME=$(basename "$schema_file" .json)
echo "Processing $SCHEMA_NAME..."
# Upload schema
UPLOAD_ID=$(escape-cli upload schema < "$schema_file" -o json | jq -r '.id')
if [ -z "$UPLOAD_ID" ]; then
echo " ✗ Failed to upload schema"
continue
fi
# Create profile
cat > temp-profile.json << EOF
{
"name": "$SCHEMA_NAME Profile",
"schema_upload_id": "$UPLOAD_ID"
}
EOF
PROFILE_ID=$(escape-cli profiles create-rest < temp-profile.json -o json | jq -r '.id')
rm temp-profile.json
echo " ✓ Created profile: $PROFILE_ID"
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 (limited validity period)
- 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 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 - Create profiles with uploaded schemas
- Assets Management - Organize assets with tags
- Issues Management - Filter issues by tags
- Practical Recipes - Complete workflow examples