EASM API Integration Guide

Overview

The EASM API integration allows your NINA workflows to connect with the internal External Attack Surface Management (EASM) service for comprehensive security posture assessment. This integration enables you to retrieve IP addresses, assets, security findings, network services, SSL certificates, web endpoints, CVEs, technologies, domains, APIs, roots, and blacklists from your EASM platform directly within your workflows.

This is an internal integration service designed for security teams to access attack surface management data within your organization's security infrastructure.

Status

The integration currently supports comprehensive EASM data retrieval across multiple resource types:

• IP Management: Retrieve grouped IP addresses with filtering and pagination
• Asset Discovery: Access detailed asset information with comprehensive filtering
• Security Findings: Query security findings with status, severity, and tool-based filtering
• Network Services: Retrieve network service information with port and protocol filtering
• SSL Certificates: Access certificate data with sorting and pagination
• Web Endpoints: Query web endpoints with URL, status code, and technology filtering
• CVE Information: Retrieve CVE data with technology inclusion options
• Technology Stack: Query detected technologies with version filtering
• Domain Management: Access domain information with relationship filtering
• API Discovery: Retrieve discovered APIs with confirmation status filtering
• Root Management: Fetch project roots with type and status filtering
• Blacklist Management: Retrieve blacklist entries with type-based filtering

Some features not yet supported include:

• Write Operations: Creating, updating, or deleting EASM resources
• Real-time Monitoring: Webhook-based notifications for new findings
• Bulk Operations: Batch processing of multiple resources simultaneously
• Custom Scanning: Initiating new scans or customizing scan parameters

Credential Configuration

Before using the EASM API integration in your workflows, you need to configure credentials for authentication. The integration uses client credentials authentication for secure access to the internal EASM service.

Authentication Method

The EASM API integration uses client credentials authentication:

Client Credentials Authentication

Authentication using client ID and secret:

Field	Description	Example
Client ID	Client ID for authentication	client_123456789
Secret	Secret for authentication	secret_abcdef123456789

How to obtain your Client Credentials:

1. Contact your organization's security team or administrator for access to the EASM API
2. Request client credentials for the service
3. Obtain the client ID and secret for authentication
4. Ensure your client has the necessary permissions for EASM data access

Note: This is an internal integration service typically used within your organization's security infrastructure. Access is restricted to authorized security personnel only.

Creating an EASM API Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "EASM API Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "EASM API"
   • Client ID: Enter your client ID
   • Secret: Enter your client secret

4. Click Test Connection to verify credentials

5. Click Save to store the credential

Supported Resources and Operations

The EASM API integration supports the following resource and operations:

EASM Data

Operation	Description
Get IPs	List IP addresses with pagination and filtering
Get Assets	Fetch detailed information about assets including hosts, IPs, and services
Get Findings	Fetch security findings
Get Services	Fetch network services discovered
Get Certificates	Fetch SSL/TLS certificates discovered
Get Endpoints	Fetch web endpoints discovered
Get CVEs	Fetch Common Vulnerabilities and Exposures (CVEs)
Get Technologies	Fetch technologies discovered
Get Domains	Fetch domains discovered
Get APIs	Fetch APIs discovered
Get Roots	Fetch roots associated with the project with filtering, pagination, and sorting options
Get Blacklists	Retrieve blacklist entries associated with the project with filtering options

Parameter Merging

The EASM API integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the EASM API Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When an EASM API Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the EASM API operation

Examples

Retrieving IP Addresses

Below is an example of retrieving grouped IP addresses:

Node Configuration:

{
  "resource": "easm",
  "operation": "getIps",
  "parameters": {
    "asset_ids": ["asset-123", "asset-456"],
    "ip": "192.168.1.100",
    "version": "IPv4",
    "country": "US",
    "city": "New York",
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve IPv4 addresses from the specified asset IDs, located in New York, US, sorted by creation date in descending order.

Retrieving Security Findings

Example of retrieving security findings with filtering:

Node Configuration:

{
  "resource": "easm",
  "operation": "getFindings",
  "parameters": {
    "endpoint_id": "endpoint-789",
    "status": "open",
    "tool": "nessus",
    "target": "https://example.com/login",
    "type": "vulnerability",
    "tags": ["critical", "exploitable"],
    "name": "SQL Injection",
    "severity": "high",
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 25
    }
  }
}

This will retrieve open, high-severity vulnerabilities found by Nessus on a specific endpoint, tagged as critical and exploitable.

Retrieving Asset Information

Example of retrieving detailed asset information:

Node Configuration:

{
  "resource": "easm",
  "operation": "getAssets",
  "parameters": {
    "root_id": "root-123",
    "host": "example.com",
    "ip": "203.0.113.100",
    "version": "IPv4",
    "country": "US",
    "protocol": "https",
    "port": 443,
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 100
    }
  }
}

This will retrieve assets for the example.com domain with the specified IP, using HTTPS on port 443, sorted by creation date.

Retrieving Network Services

Example of retrieving network services:

Node Configuration:

{
  "resource": "easm",
  "operation": "getServices",
  "parameters": {
    "asset_id": "asset-123",
    "ip_id": "ip-456",
    "port": 80,
    "protocol": "tcp",
    "sortBy": "created_at",
    "sortOrder": "ASC",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve TCP services on port 80 for a specific asset and IP, sorted by creation date.

Retrieving SSL Certificates

Example of retrieving SSL/TLS certificates:

Node Configuration:

{
  "resource": "easm",
  "operation": "getCertificates",
  "parameters": {
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve SSL/TLS certificates sorted by creation date in descending order.

Retrieving Web Endpoints

Example of retrieving web endpoints with filtering:

Node Configuration:

{
  "resource": "easm",
  "operation": "getEndpoints",
  "parameters": {
    "asset_id": "asset-123",
    "url": "https://api.example.com",
    "status_code": 200,
    "favicon": "default.ico",
    "tech": "nginx",
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 75
    }
  }
}

This will retrieve successful endpoints (status 200) using nginx technology with a specific favicon.

Retrieving CVE Information

Example of retrieving CVE information with technology details:

Node Configuration:

{
  "resource": "easm",
  "operation": "getCves",
  "parameters": {
    "include_technologies": true,
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve CVEs with associated technology information, sorted by creation date in descending order.

Retrieving Technology Stack

Example of retrieving detected technologies:

Node Configuration:

{
  "resource": "easm",
  "operation": "getTechnologies",
  "parameters": {
    "endpoint_id": "endpoint-456",
    "tech": "nginx",
    "version": "1.18.0",
    "sortBy": "created_at",
    "sortOrder": "ASC",
    "pagination": {
      "from": 1,
      "size": 100
    }
  }
}

This will retrieve nginx version 1.18.0 technologies associated with a specific endpoint.

Retrieving Domain Information

Example of retrieving domain information:

Node Configuration:

{
  "resource": "easm",
  "operation": "getDomains",
  "parameters": {
    "domain": "example.com",
    "related_root": "root-domain-123",
    "sort_by": "domain_name",
    "sort_order": "asc",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve domain information for example.com and its related root domain.

Retrieving API Information

Example of retrieving discovered APIs:

Node Configuration:

{
  "resource": "easm",
  "operation": "getApis",
  "parameters": {
    "confirmed": true,
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 25
    }
  }
}

This will retrieve confirmed APIs sorted by creation date.

Retrieving Root Information

Example of retrieving project roots:

Node Configuration:

{
  "resource": "easm",
  "operation": "getRoots",
  "parameters": {
    "ids": ["root-123", "root-456"],
    "root": "example.com",
    "type": "domain",
    "active": true,
    "exclude_blacklisted_cidrs": false,
    "sortBy": "created_at",
    "sortOrder": "DESC",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve active domain roots, including example.com, sorted by creation date.

Retrieving Blacklist Information

Example of retrieving blacklist entries:

Node Configuration:

{
  "resource": "easm",
  "operation": "getBlacklists",
  "parameters": {
    "blacklist_type": "ip",
    "pagination": {
      "from": 1,
      "size": 50
    }
  }
}

This will retrieve IP blacklist entries with pagination.

Response Structure

Standard Response Format

All EASM API operations return responses in a consistent structure:

{
  "data": [
    {
      "id": "resource-id",
      "field1": "value1",
      "field2": "value2",
      // Additional resource-specific fields
    }
  ],
  "pagination": {
    "from": 0,
    "size": 50,
    "total": 250
  },
  "total": 250
}

IP Addresses Response

The getIps operation returns grouped IP address information:

{
  "ips": [
    {
      "id": "ip-123",
      "ip": "192.168.1.100",
      "version": "4",
      "country": "US",
      "city": "New York",
      "asset_ids": ["asset-123", "asset-456"],
      "ports": [80, 443, 8080],
      "services": ["http", "https"],
      "lastSeen": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "from": 0,
    "size": 50,
    "total": 150
  },
  "total": 150
}

Security Findings Response

The getFindings operation returns security finding information:

{
  "data": [
    {
      "id": "finding-789",
      "name": "SQL Injection Vulnerability",
      "severity": "high",
      "status": "open",
      "type": "vulnerability",
      "tool": "nessus",
      "target": "https://example.com/login",
      "description": "SQL injection vulnerability found in login form",
      "cvss_score": 8.5,
      "tags": ["critical", "exploitable"],
      "endpoint_id": "endpoint-456",
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "from": 0,
    "size": 25,
    "total": 75
  },
  "total": 75
}

Integration in Workflow Context

The EASM API integration is particularly effective when combined with other security and monitoring nodes:

Common Workflow Patterns:

1. Security Posture Assessment:

   • Schedule Node → EASM API Node (getFindings) → Filter Node (high severity) → Slack Integration Node (alert team)

2. Asset Inventory Management:

   • EASM API Node (getAssets) → Script Node (process asset data) → Database Node (store inventory) → Report Node (generate asset report)

3. Root Domain Monitoring:

   • EASM API Node (getRoots) → Script Node (check root status) → EASM API Node (getAssets) → Filter Node (new assets) → Email Node (send notifications)

4. Vulnerability Prioritization:

   • EASM API Node (getCves) → Script Node (calculate risk scores) → EASM API Node (getAssets) → Jira Integration Node (create tickets)

5. Technology Stack Monitoring:

   • EASM API Node (getTechnologies) → Script Node (check for outdated versions) → Email Node (send update notifications)

6. Certificate Monitoring:

   • Schedule Node → EASM API Node (getCertificates) → Script Node (check expiration) → Alert Node (expiring certificates)

7. API Discovery and Documentation:

   • EASM API Node (getApis) → Script Node (format API documentation) → Confluence Integration Node (update documentation)

8. Blacklist Management:

   • EASM API Node (getBlacklists) → Script Node (validate entries) → Database Node (update local blacklist) → Security Tool Node (apply rules)

9. Comprehensive Attack Surface Analysis:

   • EASM API Node (getRoots) → EASM API Node (getAssets) → EASM API Node (getFindings) → Script Node (correlate data) → Dashboard Node (visualize surface)

10. Service Discovery and Port Monitoring:

    • EASM API Node (getServices) → Filter Node (critical ports) → EASM API Node (getFindings) → Alert Node (vulnerable services)

Advanced Features

Comprehensive Filtering Options

The integration supports extensive filtering across all operations:

{
  "parameters": {
    "ip": "192.168.1.100",
    "country": "US",
    "port": 443,
    "protocol": "https",
    "status": "active"
  }
}

Flexible Pagination

All operations support consistent pagination parameters:

{
  "pagination": {
    "from": 1,    // Starting page number
    "size": 50    // Number of results per page
  }
}

Advanced Sorting

Operations support flexible sorting with field selection and direction:

{
  "sortBy": "created_at",
  "sortOrder": "DESC"  // or "ASC"
}

Array Parameter Handling

For operations that accept arrays (like asset IDs or tags), the integration properly handles multiple values:

{
  "asset_ids": ["asset-123", "asset-456", "asset-789"],
  "tags": ["critical", "exploitable", "production"]
}

Root Type Filtering

The getRoots operation supports filtering by root types:

{
  "type": "domain",     // or "cidr", "asn"
  "active": true,
  "exclude_blacklisted_cidrs": false
}

Blacklist Type Management

The getBlacklists operation supports type-based filtering:

{
  "blacklist_type": "ip"  // or "asset"
}

Best Practices

1. Use Pagination: Always implement pagination for large result sets to avoid timeouts and memory issues.

2. Filter Effectively: Use specific filters to reduce the volume of data transferred and improve performance.

3. Sort Strategically: Use sorting to prioritize the most relevant results first (e.g., sort findings by severity).

4. Cache Results: For frequently accessed data, consider caching results to reduce API calls.

5. Handle Token Expiration: Implement error handling for token expiration and renewal scenarios.

6. Batch Related Operations: When retrieving multiple resource types, batch the operations for better performance.

7. Use Specific Asset IDs: When possible, filter by specific asset IDs to reduce the scope of operations.

8. Monitor Rate Limits: Be aware of any rate limiting in your EASM API and implement appropriate delays.

9. Validate Input Parameters: Always validate input parameters before passing them to the integration.

10. Error Handling: Implement comprehensive error handling for network issues, authentication failures, and invalid parameters.

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
Authentication failed	Verify client ID and secret are valid; check credential permissions
Access denied	Ensure client credentials have necessary permissions for EASM data access
Connection timeout	Check network connectivity to EASM API; verify internal service availability
Invalid parameters	Validate parameter names and types; check API documentation for required fields
No results returned	Verify filtering parameters are not too restrictive; check if data exists
Rate limit exceeded	Implement delays between requests; reduce request frequency
Invalid sorting field	Verify sortBy field names match the API specification
Pagination errors	Ensure 'from' and 'size' parameters are within valid ranges

Error Response Format

The integration returns standardized error responses:

{
  "error": true,
  "message": "Authentication failed: Invalid client credentials",
  "details": {
    "statusCode": 401,
    "operation": "getIps",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Support

If you encounter issues with the EASM API integration, please contact our support team with:

• The operation you were attempting
• Your credential configuration (without sensitive data)
• Any error messages received
• The workflow context where the issue occurred

This information will help us provide faster and more accurate assistance.