Cortex API Client for Rust

Cortex is an open-source, powerful observable analysis and active response engine. It allows security professionals and SOC analysts to analyze observables like IPs, URLs, domains, files, and more, using a wide array of integrated analyzers. It also enables automated responses to threats through its responder capabilities.

The Cortex API provides a programmatic interface to its rich set of features, offering several advantages:

• Automation: Automate the submission of observables for analysis, streamlining workflows and reducing manual effort.
• Integration: Seamlessly integrate Cortex's analysis capabilities into existing security tools and platforms (SIEMs, SOARs, TIPs, etc.).
• Scalability: Handle large volumes of observables and analysis requests programmatically.
• Customization: Build custom scripts and tools that leverage Cortex's backend for tailored security operations.
• Efficiency: Speed up incident response by getting analysis results quickly and consistently.

Adding the Crate to Your Project

To integrate the cortex-client-rs into your Rust project, add it as a dependency in your Cargo.toml file.

[dependencies]
cortex-client-rs = "0.1" 

Running The Examples from this Repository

This repository includes several runnable examples in the examples/ directory. To run them:

1. Set Environment Variables: Ensure your Cortex instance is running and accessible. You'll need to set the following environment variables:

   • CORTEX_ENDPOINT: The full URL to your Cortex API (e.g., http://localhost:9000/api).
   • CORTEX_API_KEY: Your API key for authenticating with Cortex.

   Example:

   export CORTEX_ENDPOINT="http://your-cortex-host:9000/api"
   export CORTEX_API_KEY="your_cortex_api_key"
   

2. Run an Example: Use cargo run --example <example_name>. For instance, to run the abuseipdb_example:

   cargo run --example abuseipdb_example
   

   Replace abuseipdb_example with the name of any other example file in the examples/ directory (e.g., list_analyzers, status_example).

Rust Usage Examples

Below are examples of how to use the generated Rust client to interact with the Cortex API, focusing on running analyzers. These examples are structured similarly to the runnable files found in the examples/ directory of this repository.

Note:

• These examples assume the client has been generated and is available as the client crate.
• They rely on a helper module, typically named common.rs (as seen in the examples/ directory), which should provide:
  • setup_configuration(): A function to create a client::apis::configuration::Configuration object, usually by reading CORTEX_ENDPOINT and CORTEX_API_KEY from environment variables.
  • get_analyzer_id_by_name(config: &Configuration, analyzer_name: &str) -> Result<Option<String>, Box<dyn std::error::Error>>: A function to find an analyzer's instance ID given its name.
• Ensure your Cortex instance is running and accessible, and your API key is valid.
• Error handling is included for clarity.

1. Analyze an IP Address

This example demonstrates how to submit an IP address to an analyzer like VirusTotal. It assumes you have a common.rs module for setup.

// main.rs (or your example file)
use cortex_client::apis::job_api;
use cortex_client::models::JobCreateRequest;

mod common;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = match common::setup_configuration() {
        Ok(cfg) => cfg,
        Err(e) => {
            eprintln!("Configuration error: {}", e);
            eprintln!("Please ensure CORTEX_ENDPOINT and CORTEX_API_KEY environment variables are set.");
            return Err(e.into());
        }
    };

    let analyzer_name_to_run = "VirusTotal_GetReport_3_1"; // Example analyzer name
    let ip_to_analyze = "8.8.8.8";
    let data_type = "ip";

    let analyzer_worker_id = match common::get_analyzer_id_by_name(&config, analyzer_name_to_run).await {
        Ok(Some(id)) => id,
        Ok(None) => {
            eprintln!("Could not find an analyzer instance named '{}'. Ensure it's enabled in Cortex.", analyzer_name_to_run);
            return Ok(());
        }
        Err(e) => {
            eprintln!("Error getting analyzer ID for '{}': {}", analyzer_name_to_run, e);
            return Err(e);
        }
    };

    println!(
        "Attempting to run analyzer '{}' (ID: '{}') on IP: {}",
        analyzer_name_to_run, analyzer_worker_id, ip_to_analyze
    );

    let job_create_request = JobCreateRequest {
        data: Some(ip_to_analyze.to_string()),
        data_type: Some(data_type.to_string()),
        tlp: Some(2), // Traffic Light Protocol: AMBER
        pap: Some(2), // Permissible Actions Protocol: AMBER
        message: Some(Some(format!(
            "README example: Analyzing IP {} with {}",
            ip_to_analyze, analyzer_name_to_run
        ))),
        parameters: None,
        label: Some(Some(format!("readme_ip_analysis_{}", ip_to_analyze))),
        force: Some(false),
        attributes: None,
    };

    match job_api::create_analyzer_job(&config, &analyzer_worker_id, job_create_request).await {
        Ok(job_details) => {
            println!(
                "Successfully submitted job for {} '{}' with analyzer '{}'. Job ID: {}",
                data_type,
                ip_to_analyze,
                analyzer_name_to_run,
                job_details._id.unwrap_or_default()
            );
            println!("Job details: {:#?}", job_details);
        }
        Err(e) => {
            eprintln!("Error submitting IP analysis job: {:?}", e);
            eprintln!("Please check if analyzer '{}' (ID: '{}') is correctly configured and enabled.", analyzer_name_to_run, analyzer_worker_id);
        }
    }
    Ok(())
}

2. Analyze a File Hash

This example shows how to submit a file hash (e.g., MD5, SHA256) for analysis using an analyzer like HybridAnalysis.

use cortex_client::apis::job_api;
use cortex_client::models::JobCreateRequest;

mod common; 

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = match common::setup_configuration() {
        Ok(cfg) => cfg,
        Err(e) => {
            eprintln!("Configuration error: {}", e);
            return Err(e.into());
        }
    };

    let analyzer_name_to_run = "HybridAnalysis_GetReport_1_0"; 
    let file_hash_to_analyze = "d41d8cd98f00b204e9800998ecf8427e"; /
    let data_type = "hash"; 

    let analyzer_worker_id = match common::get_analyzer_id_by_name(&config, analyzer_name_to_run).await {
        Ok(Some(id)) => id,
        Ok(None) => {
            eprintln!("Could not find an analyzer instance named '{}'.", analyzer_name_to_run);
            return Ok(());
        }
        Err(e) => {
            eprintln!("Error getting analyzer ID for '{}': {}", analyzer_name_to_run, e);
            return Err(e);
        }
    };

    println!(
        "Attempting to run analyzer '{}' (ID: '{}') on hash: {}",
        analyzer_name_to_run, analyzer_worker_id, file_hash_to_analyze
    );

    let job_create_request = JobCreateRequest {
        data: Some(file_hash_to_analyze.to_string()),
        data_type: Some(data_type.to_string()),
        tlp: Some(2),
        pap: Some(2),
        message: Some(Some(format!(
            "README example: Analyzing file hash {} with {}",
            file_hash_to_analyze, analyzer_name_to_run
        ))),
        parameters: None,
        label: Some(Some(format!("readme_hash_analysis_{}", file_hash_to_analyze))),
        force: Some(false),
        attributes: None,
    };

    match job_api::create_analyzer_job(&config, &analyzer_worker_id, job_create_request).await {
        Ok(job_details) => {
            println!(
                "Successfully submitted job for {} '{}' with analyzer '{}'. Job ID: {}",
                data_type,
                file_hash_to_analyze,
                analyzer_name_to_run,
                job_details._id.unwrap_or_default()
            );
            println!("Job details: {:#?}", job_details);
        }
        Err(e) => {
            eprintln!("Error submitting file hash analysis job: {:?}", e);
        }
    }
    Ok(())
}

Note on analyzing files: To analyze an actual file (not just its hash), you would typically set dataType: "file" and send the file content as a multipart/form-data request. The JobCreateRequest schema anticipates an attachment part for this. Your Rust HTTP client library would need to support multipart uploads. The specifics of constructing such a request depend on the generated client's capabilities for handling file uploads.

3. Analyze a Domain with Custom Parameters

Some analyzers accept specific parameters. This example shows submitting a domain with custom parameters, using serde_json::json to construct them.

use cortex_client::apis::job_api;
use cortex_client::models::JobCreateRequest;
use serde_json::json; 

mod common; 

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = match common::setup_configuration() {
        Ok(cfg) => cfg,
        Err(e) => {
            eprintln!("Configuration error: {}", e);
            return Err(e.into());
        }
    };

    let analyzer_name_to_run = "DomainToolsIris_Investigate_1_0"; 
    let domain_to_analyze = "example.com";
    let data_type = "domain";

    let analyzer_worker_id = match common::get_analyzer_id_by_name(&config, analyzer_name_to_run).await {
        Ok(Some(id)) => id,
        Ok(None) => {
            eprintln!("Could not find an analyzer instance named '{}'.", analyzer_name_to_run);
            return Ok(());
        }
        Err(e) => {
            eprintln!("Error getting analyzer ID for '{}': {}", analyzer_name_to_run, e);
            return Err(e);
        }
    };

    println!(
        "Attempting to run analyzer '{}' (ID: '{}') on domain: {}",
        analyzer_name_to_run, analyzer_worker_id, domain_to_analyze
    );

    let custom_params = json!({
        "include_subdomains": true,
        "max_history_days": 90
    });

    let job_create_request = JobCreateRequest {
        data: Some(domain_to_analyze.to_string()),
        data_type: Some(data_type.to_string()),
        tlp: Some(1), // Traffic Light Protocol: GREEN
        pap: Some(1), // Permissible Actions Protocol: GREEN
        message: Some(Some(format!(
            "README example: Analyzing domain {} with {} and custom parameters",
            domain_to_analyze, analyzer_name_to_run
        ))),
        parameters: Some(custom_params),
        label: Some(Some(format!("readme_domain_analysis_{}", domain_to_analyze))),
        force: Some(false),
        attributes: None,
    };

    match job_api::create_analyzer_job(&config, &analyzer_worker_id, job_create_request).await {
        Ok(job_details) => {
            println!(
                "Successfully submitted job for {} '{}' with analyzer '{}'. Job ID: {}",
                data_type,
                domain_to_analyze,
                analyzer_name_to_run,
                job_details._id.unwrap_or_default()
            );
            println!("Job details: {:#?}", job_details);
        }
        Err(e) => {
            eprintln!("Error submitting domain analysis job with parameters: {:?}", e);
        }
    }
    Ok(())
}

After submitting a job, you would typically use the returned Job ID to poll its status using JobApi::get_job_by_id and, once completed successfully, retrieve the full report using JobApi::get_job_report. You can also use JobApi::wait_job_report to long-poll for the result.

Documentation for API Endpoints

All URIs are relative to /api

Documentation For Models

• AnalyzerConfigUpdateRequest
• AnalyzerCreateRequest
• AnalyzerFindRequest
• Artifact
• Attachment
• AuthContext
• BaseConfig
• ConfigurationDefinitionItem
• ConfigurationDefinitionItemDefaultValue
• DbListAddItemRequest
• DbListItemExistsRequest
• DbListItemExistsResponse
• Error
• FindAnalyzers200Response
• FindOrganizations200Response
• FindUsers200Response
• HealthResponse
• Job
• JobCreateRequest
• JobData
• JobReportResponse
• JobReportResponseOneOf
• JobStatusRequest
• ListAnalyzerDefinitions200Response
• ListJobArtifacts200Response
• ListJobs200Response
• ListMispModules200Response
• LoginRequest
• MispModule
• MispModuleMeta
• MispModuleMispattributes
• MispQueryRequest
• MispQueryResponse
• MispQueryResponseResultsInner
• Organization
• OrganizationCreateRequest
• OrganizationFindRequest
• OrganizationStatsRequest
• OrganizationUpdateRequest
• PasswordChangeRequest
• PasswordSetRequest
• ResponderConfigUpdateRequest
• ResponderCreateRequest
• ResponderFindRequest
• StatusResponse
• StatusResponseConfig
• StatusResponseConfigAuthType
• StatusResponseVersions
• StreamMessagesResponse
• StreamStatusResponse
• User
• UserCreateRequest
• UserUpdateRequest
• Worker
• WorkerConfiguration
• WorkerDefinition

To get access to the crate's generated documentation, use:

cargo doc --open