npm package: @gillesvilleneuve/crowdstrike-falcon
Description: CrowdStrike Falcon integration for Active Pieces with incident management, host isolation, and real-time response capabilities
Latest version: 0.2.0

# CrowdStrike Falcon Integration for Active Pieces

This custom piece for Active Pieces provides integration with CrowdStrike Falcon, enabling security automation workflows with capabilities for incident management, host isolation, and real-time response.

## Features

- **Incident Management**: Search, retrieve, and update incidents
- **Host Isolation**: Isolate hosts, lift isolation, and check isolation status
- **Real-Time Response**: Initialize sessions, execute commands, and retrieve files
- **MSSP Support**: Flexible authentication for managing multiple customer environments

## Installation

### Prerequisites

- Active Pieces environment (version 0.5.0 or higher)
- CrowdStrike Falcon API credentials (Client ID and Client Secret)
- Node.js and npm

### Setup Instructions

1. Clone this repository or download the source code
2. Navigate to the project directory
3. Install dependencies:
   ```
   npm install
   ```
4. Build the piece:
   ```
   npm run build
   ```
5. Deploy the built piece to your Active Pieces environment

## Authentication

This integration uses OAuth2 authentication with CrowdStrike Falcon API. You'll need to provide:

- **API Base URL**: Your CrowdStrike API endpoint (e.g., https://api.crowdstrike.com)
- **Client ID**: Your CrowdStrike API client ID
- **Client Secret**: Your CrowdStrike API client secret

Each MSSP customer environment can have its own authentication configuration.

## Available Actions

### Incident Management

- **Search Incidents**: Search for incidents using FQL filters with sorting and paging
- **Get Incident Details**: Retrieve detailed information about specific incidents by their IDs
- **Update Incidents**: Perform actions on incidents such as status updates, assignment, or tagging

### Host Isolation

- **Isolate Host**: Isolate a host from the network
- **Lift Host Isolation**: Remove isolation from a previously isolated host
- **Check Host Isolation Status**: Check the current isolation status of a host

### Real-Time Response

- **Initialize RTR Session**: Create a new RTR session with a host
- **Execute RTR Command**: Execute a read-only or active responder command on a host
- **Check RTR Command Status**: Check the status of a previously executed command
- **Get RTR File Contents**: Retrieve file contents extracted during an RTR session

## Usage Examples

### Incident Response Workflow

1. Use the "Search Incidents" action to find new high-severity incidents
2. For each incident, use "Get Incident Details" to retrieve full information
3. If the incident involves a compromised host, use "Isolate Host" to contain the threat
4. Use "Initialize RTR Session" and "Execute RTR Command" to gather forensic information
5. Update the incident status using "Update Incidents"

### Threat Hunting

1. Initialize RTR sessions with multiple hosts
2. Execute commands to search for indicators of compromise
3. Retrieve and analyze file contents for suspicious activity
4. Isolate hosts if threats are detected

## MSSP Implementation

For MSSP scenarios, this integration supports:

1. Environment-specific authentication for each customer
2. Parameterization of all actions
3. Proper error handling and retry mechanisms
4. Detailed logging for troubleshooting
5. Batch operations where applicable

## Troubleshooting

- Ensure your CrowdStrike API credentials have the necessary permissions
- Check that the API Base URL is correct for your environment
- Verify that the device IDs used in host isolation and RTR actions are valid
- For RTR actions, ensure that the session is initialized before executing commands

## Support

For issues or feature requests, please contact your Active Pieces administrator or submit an issue in the repository.