Getting Started

LogCraft CLI, or lgc in short, has been designed to be integrated into a CI/CD pipeline but it can also be used as a command line utility from your workstation.

At a high level, LogCraft CLI is pretty straightforward as it reads detection files and manage them programmatically.

Quickstart

First, let's create a workspace.

~$ mkdir getting-started
~$ cd getting-started
~$ lgc init
~$ ls -1
lgc.yaml
rules
~$

The file lgc.yaml is the main configuration file, and the rules folder is where detections rules will be stored.

TIP

In a standard configuration, both the lgc.yaml file and the rules folder are stored in a Git repository. This approach guarantees that the detections are both traceable and centralized.

Now, let's assume we only have a production environment with a Splunk server.

First, we install the required plugin to communicate with Splunk.

~$ lgc plugins install ~/Downloads/splunk.wasm

Plugins

Plugins can be found in their own repository

Then, we define a service named splunk-prod that uses the plugin splunk (i.e. a Splunk instance)

~$ lgc services add -p splunk splunk-prod

Once the service is created, we configure it:

~$ lgc services configure splunk-prod
Splunk Configuration:
✔ Splunk URL · https://some-url-to-splunk:8089
✔ Authorization scheme · "Bearer"
✔ Authorization (hidden) · ********
✔ Timeout in seconds · 30
 INFO service `splunk-prod` configured
~$

With that, we create a 'prod' environment and we attach our service splunk-prod to it:

~$ lgc envs add prod
~$ lgc envs link prod -s splunk-prod

Finally, we ensure the communication is working with our Splunk server

~$ lgc services ping
/ splunk-prod ... OK
~$

Our configuration is completed, we can now create and deploy detections to Splunk!

What is a detection?

A detection is a self-contained YAML file, with a set of defined blocks, that describes one or multiple technological implementations (i.e. the search queries) and contextual information related to the detection.

Here is what a minimum detection file will look like:

name: <name of the detection>

rules:
    <technology-1>:
         // Technology specific implementation
    <technology-2>:
         // Technology specific implementation

Here is for example a Splunk detection:

name: High Entropy Domain (DGA)

rules:
    splunk:
        app: SA-ButterCup-App
        savedsearch:
            search: |-
                index=main sourcetype=proxy url=*
                | eval list = "mozilla"
                | `ut_parse_extended(url, list)`
                | stats sum(count) as count values(src_ip) by ut_domain
                | `ut_shannon(ut_domain)`
                | search ut_shannon>3
            cron_schedule: 10 0 0 0 0
            disabled: False
            description: |-
                Detect high entropy domains which may be related to
                domain generated algorithm (DGA).
            action.correlationsearch.annotations: |-
                {
                    "mitre_attack": ['TA0011', 'T1071.004'],
                    ...
                }

Plugins

Refer to each plugin documentation to understand applicable configuration options.

Deploy a detection

Let's assume we have created 2 detections rules as illustrated below.

~$ ls -1
lgc.yaml
rules
~$ ls -1 rules/
rule-high-entropy-domain-dga.yaml
rule-crazy-high-entropy-domain.yaml
~$

First, we are going to ensure we don't have any error in our detections

~$ lgc validate
 INFO all good, no problems identified
~$

TIP

The lgc validate command ensure the content of the detection files is valid, see lgc validate.

Then, let's see if these rules are already deployed in our prod environment

~$ lgc diff prod
[+] rule: `[DGA] High Entropy Domains` will be created on `splunk-prod`
[+] rule: `Crazy High Entropy Domains` will be created on `splunk-prod`
~$

INFO

The diff command only show the differences from what's live on the remote systems and what's described in the local detection files. A detection that matches its yaml description will not be displayed.

Great, so let's deploy our rules.

~$ lgc deploy prod --auto-approve
[+] rule: `Crazy High Entropy Domains` created on `splunk-prod`
[+] rule: `[DGA] High Entropy Domains` created on `splunk-prod`

Now, let's modify the "DGA" rule by editing the Yaml file and changing the value of the disabled flag.

% lgc diff prod
[~] rule: `[DGA] High Entropy Domains` will be updated on `splunk-prod`:
|   {
|     "app": "search",
|     "savedsearch": {
|       "cron_schedule": "10 0 * * *",
| -     "disabled": true,
| +     "disabled": false,
|       "search": "index=proxy ...."
|     }
|   }

The diff command highlights the differences between what's live on remote systems and what is expected from the yaml files. So, to deploy the changes, simply run lgc deploy prod.