@gillesvilleneuve/crowdstrike-falcon/mapping.md

CrowdStrike Falcon integration for Active Pieces with incident management, host isolation, and real-time response capabilities

# Mapping Shuffle SOAR CrowdStrike Actions to Active Pieces

This document maps the CrowdStrike Falcon actions from Shuffle SOAR to their equivalent implementations in Active Pieces, focusing on the key requirements:
1. Getting alerts/incidents
2. Host isolation functionality
3. Real-time response capabilities
4. Custom authentication for MSSP environments

## Authentication Mapping

### Shuffle SOAR Authentication
In Shuffle SOAR, CrowdStrike authentication is implemented using OAuth2:
- Action: `generate_oauth2_access_token`
- Authentication flow requires client_id and client_secret
- Tokens expire after 30 minutes and need to be refreshed

### Active Pieces Authentication Implementation
For Active Pieces, we'll implement a custom authentication that supports MSSP scenarios:

```typescript
import { createPiece, PieceAuth } from '@activepieces/pieces-framework';

export const crowdstrikeAuth = PieceAuth.CustomAuth({
  props: {
    base_url: PieceAuth.SecretText({
      displayName: 'API Base URL',
      description: 'The base URL for your CrowdStrike API (e.g., https://api.crowdstrike.com)',
      required: true,
    }),
    client_id: PieceAuth.SecretText({
      displayName: 'Client ID',
      description: 'Your CrowdStrike API client ID',
      required: true,
    }),
    client_secret: PieceAuth.SecretText({
      displayName: 'Client Secret',
      description: 'Your CrowdStrike API client secret',
      required: true,
    }),
  },
  required: true,
});
```

This implementation allows each MSSP customer environment to have its own authentication configuration.

## Action Mapping

### 1. Incidents/Alerts Actions

| Shuffle SOAR Action | Active Pieces Action | Description |
|---------------------|----------------------|-------------|
| `get_details_on_incidents` | `getIncidentDetails` | Retrieves detailed information about specific incidents by their IDs |
| `search_for_incidents` | `searchIncidents` | Searches for incidents using FQL filters with sorting and paging |
| `perform_actions_on_incidents` | `updateIncidents` | Performs actions on incidents such as status updates, assignment, or tagging |

### 2. Host Isolation Actions

| Shuffle SOAR Action | Active Pieces Action | Description |
|---------------------|----------------------|-------------|
| Real-time Response actions for containment | `isolateHost` | Isolates a host from the network |
| Real-time Response actions for containment | `liftHostIsolation` | Removes isolation from a previously isolated host |
| Real-time Response actions for containment | `checkHostIsolationStatus` | Checks the current isolation status of a host |

### 3. Real-time Response Actions

| Shuffle SOAR Action | Active Pieces Action | Description |
|---------------------|----------------------|-------------|
| `Real Time Response - Initialize a new session with the RTR cloud` | `initializeRtrSession` | Creates a new RTR session |
| `Real Time Response - Execute a command on a single host` | `executeRtrCommand` | Executes a read-only command on a host |
| `Real Time Response - Execute an active responder command on a single host` | `executeActiveResponderCommand` | Executes an active responder command on a host |
| `Real Time Response - Get status of an executed command on a single host` | `checkRtrCommandStatus` | Checks the status of a previously executed command |
| `Real Time Response - Get RTR extracted file contents for specified session and sha256` | `getRtrFileContents` | Retrieves file contents extracted during an RTR session |

## Implementation Structure

The Active Pieces implementation will follow this structure:

```
crowdstrike-piece/
├── src/
│   ├── index.ts                  # Main piece definition
│   ├── auth.ts                   # Authentication implementation
│   ├── common/                   # Shared utilities
│   │   ├── constants.ts          # API endpoints and constants
│   │   └── utils.ts              # Helper functions
│   ├── actions/
│   │   ├── incidents/            # Incident-related actions
│   │   │   ├── get-incident-details.ts
│   │   │   ├── search-incidents.ts
│   │   │   └── update-incidents.ts
│   │   ├── hosts/                # Host isolation actions
│   │   │   ├── isolate-host.ts
│   │   │   ├── lift-host-isolation.ts
│   │   │   └── check-isolation-status.ts
│   │   └── rtr/                  # Real-time response actions
│   │       ├── initialize-session.ts
│   │       ├── execute-command.ts
│   │       ├── execute-active-responder-command.ts
│   │       ├── check-command-status.ts
│   │       └── get-file-contents.ts
│   └── triggers/                 # Optional triggers (future expansion)
└── package.json
```

## API Endpoints Mapping

| Functionality | CrowdStrike API Endpoint | 
|---------------|--------------------------|
| Authentication | `/oauth2/token` |
| Incidents | `/incidents/queries/incidents/v1` |
| Incident Details | `/incidents/entities/incidents/v1` |
| RTR Session Init | `/real-time-response/entities/sessions/v1` |
| RTR Command Execution | `/real-time-response/entities/command/v1` |
| Host Isolation | `/devices/entities/devices-actions/v2` |

## MSSP Use Case Implementation

For MSSP scenarios, the piece will:

1. Support environment-specific authentication for each customer
2. Allow parameterization of all actions
3. Include proper error handling and retry mechanisms
4. Provide detailed logging for troubleshooting
5. Support batch operations where applicable

This mapping provides the foundation for implementing a custom CrowdStrike piece in Active Pieces that mirrors the functionality of the Shuffle SOAR integration while adding MSSP-specific enhancements.