Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
205 lines (141 loc) · 5.33 KB

GETTING_STARTED.md

File metadata and controls

205 lines (141 loc) · 5.33 KB
Raw

Getting Started

Detailed onboarding walkthrough for talonctl.

1. Prerequisites

You need:

  • CrowdStrike Falcon tenant with NG-SIEM (LogScale) enabled
  • CrowdStrike API credentials — create an API client in the Falcon Console:
    • Go to Support & Resources > API Clients and Keys
    • Create a new client with the scopes needed for your resource types (see README for scope reference)
  • Python 3.11+ — with pip
  • Git

2. Installation

python3 -m venv .venv
source .venv/bin/activate
pip install talonctl

Dependencies (installed automatically):

  • crowdstrike-falconpy — CrowdStrike API SDK
  • pyyaml — YAML template parsing
  • rich — terminal output formatting
  • click — CLI framework
  • requests — HTTP calls

3. Setup

Scaffold a New Project

talonctl init myproject
cd myproject

This creates the full project directory structure with resource directories, knowledge base templates, state file, and .gitignore.

Configure Credentials

Run the setup wizard:

talonctl auth setup

The wizard will:

  1. Prompt for your Client ID and Client Secret
  2. Ask you to select your cloud region (US1, US2, EU1, GOV1)
  3. Validate the connection against the CrowdStrike API
  4. Save credentials to ~/.config/falcon/credentials.json with 600 permissions

If you already have credentials saved, it will show you the existing config and ask if you want to reconfigure.

Manual Setup

If you prefer to skip the wizard:

mkdir -p ~/.config/falcon
cat > ~/.config/falcon/credentials.json << 'EOF'
{
  "falcon_client_id": "YOUR_CLIENT_ID",
  "falcon_client_secret": "YOUR_CLIENT_SECRET",
  "base_url": "US1"
}
EOF
chmod 600 ~/.config/falcon/credentials.json

Valid base_url values: US1, US2, EU1, GOV1.

4. Import Your First Resources

If you already have detections, saved searches, or other resources in your CrowdStrike tenant, import them to bring them under IaC management.

Preview the Import

talonctl import --plan

This connects to your tenant, discovers existing resources, and shows what would be imported — without changing anything.

Run the Import

# Import detection rules
talonctl import --resources=detection

# Import saved searches
talonctl import --resources=saved_search

# Import multiple types at once
talonctl import --resources=detection,saved_search,workflow

# Import everything
talonctl import

What happens:

  • YAML templates are generated in resources/<type>/ for each discovered resource
  • The state file (.crowdstrike/deployed_state.json) is created/updated
  • Each resource gets a stable resource_id — never change this after import

Verify

# Check the generated templates
ls resources/detections/

# Validate all templates parse correctly
talonctl validate

# Show current state
talonctl show

5. Plan and Deploy

# See what would change
talonctl plan

# Deploy (after reviewing the plan)
talonctl apply

6. CI/CD Setup

Two GitHub Actions workflows are included in .github/workflows/:

plan-and-deploy.yml

  • Trigger: PR opened/updated, or push to main
  • PR behavior: Runs plan, posts summary as PR comment
  • Main branch behavior: Runs apply --auto-approve

Required GitHub Secrets

Secret Value
FALCON_CLIENT_ID Your CrowdStrike API client ID
FALCON_CLIENT_SECRET Your CrowdStrike API client secret
FALCON_BASE_URL Your cloud region (e.g., US1, US2, EU1)

Set these in your GitHub repo under Settings > Secrets and variables > Actions.

weekly-template-discovery.yml

Runs weekly to discover new CrowdStrike OOTB templates. Creates a PR with any new templates found for your review.

7. Using with AI Skills (Optional)

If you want AI-assisted SOC operations on top of talonctl, see the agent-skills repo. To set it up:

  1. Install the agent-skills plugins into Claude Code
  2. The integrated instructions are already in this project's CLAUDE.md
  3. Configure a CrowdStrike MCP server for live alert/query access

8. Troubleshooting

Authentication Errors

Error: Authentication failed (401)
  • Verify credentials: cat ~/.config/falcon/credentials.json
  • Check your cloud region matches your tenant
  • Ensure the API client hasn't been revoked in the Falcon Console
  • Re-run talonctl auth setup to reconfigure

Import Finds No Resources

No resources found for type: detection
  • Confirm your API client has the required scopes (Custom IOA Rules: Read)
  • Check that you're pointing at the right tenant/region
  • Try talonctl import --plan to see the full discovery output

Plan Shows Unexpected Changes

~ update detection: my-detection (content changed)
  • Someone may have edited the detection in the Falcon Console directly
  • Run talonctl drift to see what changed
  • Run talonctl sync to pull the live version into state
  • Decide whether to keep the console change (update template) or revert it (apply)

Saved Search Description Too Long

Error: Description exceeds 2000 character limit

The CrowdStrike API silently truncates saved search descriptions beyond 2000 characters. Keep descriptions concise. The validate command catches this before deployment.