API Overview

The SmartPT API allows for seamless integration and automation of security actions across various platforms. It offers a robust and flexible solution for organizations to efficiently manage security alerts, streamline incident response, and improve overall security posture.

This API is designed for developers and security analysts who want to build automated workflows and integrate SmartPT's functionalities into their existing security systems.

Authentication

The SmartPT API uses company keys for authentication. Each company is assigned a unique company key (an SHA256 hash) during onboarding.

To authenticate your requests, include the company key in the `x-sha256` header:

curl -X POST \
  https://security-api.smartpt.co.il/ \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        // Request body
      }'

API Requests

For direct API access and automation, use the following endpoints. Include the `action` parameter in the request body to specify the desired action. All API requests require company key authentication.

Azure AD

Base URL: /azuread/users

Actions

  • AzureADBlock: Blocks a user in Azure AD. 
    curl -X POST \
  https://security-api.smartpt.co.il/azuread/users \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "AzureADBlock",
        "Email": "user@example.com",
        "upn": "user@domain.com"
      }'

    Response:

    {
  "statusCode": 200,
  "message": "User user@domain.com was blocked successfully"
}

    Possible Error Responses:

    {
  "statusCode": 400,
  "message": "Bad Request: Missing 'upn' parameter"
}

{
  "statusCode": 401,
  "message": "Unauthorized" 
}

{
  "statusCode": 500,
  "message": "Internal Server Error: Failed to block user" 
}
  • AzureADUnblock: Unblocks a user in Azure AD. 
    curl -X POST \
  https://security-api.smartpt.co.il/azuread/users \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "AzureADUnblock",
        "Email": "user@example.com",
        "upn": "user@domain.com"
      }'
  • AzureADStatus: Retrieves the status of a user in Azure AD. 
    curl -X POST \
  https://security-api.smartpt.co.il/azuread/users \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "AzureADStatus",
        "Email": "user@example.com",
        "upn": "user@domain.com"
      }'
  • AzureADSreport: Generates and sends an audit report for a user. 
    curl -X POST \
  https://security-api.smartpt.co.il/azuread/users \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "AzureADSreport",
        "Email": "user@example.com",
        "upn": "user@domain.com"
      }'

Wazuh

Base URL: /wazuh/agents

Actions

  • isolate: Isolates an agent in Wazuh. 
    curl -X POST \
  https://security-api.smartpt.co.il/wazuh/agents \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "isolate",
        "Email": "user@example.com",
        "agent_id": "your_agent_id"
      }'
  • releaseisolate: Releases an agent from isolation in Wazuh. 
    curl -X POST \
  https://security-api.smartpt.co.il/wazuh/agents \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "releaseisolate",
        "Email": "user@example.com",
        "agent_id": "your_agent_id"
      }'
  • status: Retrieves the status of an agent in Wazuh. 
    curl -X POST \
  https://security-api.smartpt.co.il/wazuh/agents \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "status",
        "Email": "user@example.com",
        "agent_id": "your_agent_id"
      }'

Example Response (isolate)

{
  "statusCode": 200,
  "body": {
    "message": "Action executed successfully",
    "action_result": {
      // ... Wazuh API response ...
    }
  }
}

Palo Alto Networks

Base URL: /paloalto/endpoints

Actions: Same as Wazuh (isolate, releaseisolate, status)

Cisco Secure Endpoint

Base URL: /cisco/computers

Actions: Same as Wazuh (isolate, releaseisolate, status)

Get Started

For Companies

  1. Contact SmartPT to obtain your unique company key (SHA256 hash) and discuss integration options.
  2. Refer to the Service Setup Guides to integrate your chosen security platforms with the SmartPT API.
  3. Start sending API requests to automate your security actions!

Service Setup Guides

Wazuh

To integrate Wazuh with the SmartPT API, follow these steps:

  1. Download the SmartPT Wazuh parser script here.
  2. Configure the parser with your company key and API endpoint.
  3. Integrate the parser with Wazuh's Active Response feature.
  4. Example active-response.conf configuration: 
    <command>
  <name>smartpt-isolate</name>
  <executable>python3</executable>
  <arguments>/path/to/smartpt_wazuh_parser.py isolate $1</arguments>
</command>

Cortex XDR

To integrate Cortex XDR with the SmartPT API, follow these steps:

  1. Obtain your API credentials (Client ID and Client Secret) from your Cortex XDR console.
  2. Create a new API key in your Cortex XDR console with the appropriate permissions for the actions you want to perform (e.g., isolate endpoints).
  3. Store your API key securely, preferably in a secrets management solution like AWS Secrets Manager.
  4. Use the following cURL command as a template for your API requests, replacing the placeholders with your actual values:
    5. curl -X POST \
  https://security-api.smartpt.co.il/cortex/endpoints \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "isolate",  // Or "releaseisolate" or "status"
        "Email": "your_email@example.com",
        "agent_id": "your_agent_id"  // Replace with the actual agent ID or IP/hostname
      }'

Azure AD

To integrate Azure AD with the SmartPT API, follow these steps:

  1. Register a new application in your Azure AD tenant.
  2. Configure the application with the necessary API permissions for Microsoft Graph (e.g., `User.Read.All`, `User.ReadWrite.All`, `Directory.Read.All`).
  3. Grant admin consent to the configured permissions.
  4. Obtain the `tenant_id`, `client_id`, and `client_secret` for your application.
  5. Store your `client_secret` securely, preferably in a secrets management solution like AWS Secrets Manager.
  6. Use the following cURL command as a template for your API requests, replacing the placeholders with your actual values:
    7. curl -X POST \
  https://security-api.smartpt.co.il/azuread/users \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "AzureADBlock",  // Or "AzureADUnblock" or "AzureADStatus" or "AzureADSreport"
        "Email": "your_email@example.com",
        "upn": "user@domain.com"  // Replace with the actual user principal name
      }'

Microsoft Defender

To integrate Microsoft Defender with the SmartPT API, follow these steps:

  1. Obtain API credentials (tenant ID, client ID, and client secret) for accessing the Microsoft Defender for Endpoint API.
  2. Store your client secret securely, preferably in a secrets management solution like AWS Secrets Manager.
  3. Use the following cURL command as a template for your API requests, replacing the placeholders with your actual values:
    4. curl -X POST \
  https://security-api.smartpt.co.il/defender/machines \
  -H 'Content-Type: application/json' \
  -H 'x-sha256: your_company_key' \
  -d '{
        "action": "isolate",  // Or "releaseisolate" or "status"
        "Email": "your_email@example.com",
        "agent_id": "your_agent_id"  // Replace with the actual agent ID or IP/hostname
      }'

Error Handling

The SmartPT API uses standard HTTP status codes to indicate success or failure. Common codes include:

  • 400 Bad Request: Missing parameters or invalid data.
  • 401 Unauthorized: Authentication failed.
  • 500 Internal Server Error: Unexpected server error.

For troubleshooting, check request parameters, company key, and API endpoint URL. Contact SmartPT support if issues persist.

Frequently Asked Questions (FAQs)

General

What are the benefits of using the SmartPT API?
  • Automates security actions, saving time and reducing human error.
  • Provides a centralized platform for managing security across different vendors.
  • Enhances incident response capabilities.
  • Improves overall security posture.
What security platforms does SmartPT integrate with?
SmartPT integrates with Azure AD, Wazuh, Palo Alto Networks, and Cisco Secure Endpoint.
What types of actions can I perform with the API?
You can perform user management actions in Azure AD, isolate and release devices in Wazuh, Palo Alto Networks, and Cisco Secure Endpoint, and retrieve security status information.

Bot Actions

How do I access the SmartPT bot?
You can access the bot through our WhatsApp bot or website bot (provide links).
How do I authenticate with the bot?
We use a passwordless system with email-based OTP (One-Time Password).
What actions can I perform with the bot?
You can perform various user and device actions, including blocking/unblocking users, isolating/releasing devices, and retrieving status information.

API Requests

How do I authenticate my API requests?
Use your unique company key (SHA256 hash) provided during onboarding.
What is the format for sending API requests?
Send POST requests to the appropriate endpoint with the `action` and other parameters in the JSON body.

Use Cases

Here are some examples of how companies are using the SmartPT API to automate their security tasks:

  • Automated user onboarding and offboarding in Azure AD.
  • Automatic isolation of infected devices detected by Wazuh, Palo Alto Networks, or Cisco Secure Endpoint.
  • Real-time security monitoring and alerting with custom notifications.
  • Integration with ticketing systems for streamlined incident response.
  • Automated response to security incidents based on predefined rules and policies.
  • Proactive threat hunting and mitigation.

Visuals

Here are some diagrams to help you understand the SmartPT API architecture and workflows:

Architecture Diagram

Architecture Diagram of SmartPT API integration with security services and notification channels

Workflow Diagram

Workflow Diagram showing the flow of security alerts from source to notification