Introduction to Scripting for Ridgeback Policies

Scripting is a powerful and flexible way to implement custom policies in Ridgeback. While the built-in UI allows you to create and manage basic policies, scripting enables more advanced and precise control over triggers and actions by leveraging the underlying database and automation capabilities.

Why Use Scripts for Policies?

• Flexibility: Scripts allow you to define complex logic and conditions that may not be possible using the UI alone.
• Automation: They integrate seamlessly into automated workflows for monitoring and responding to network events.
• Customization: You can tailor policies to your organization's specific security and compliance requirements.
• Scalability: Scripts can be reused and adapted across different organizations or networks, making them a scalable solution for large deployments.

How Scripting Works with Ridgeback Policies

Ridgeback policies rely on triggers, which are essentially SQL queries that identify specific events or conditions in the network. Scripts provide a mechanism to:

1. Generate and execute these SQL queries dynamically.
2. Interact with Ridgeback's database to extract relevant data.
3. Apply logic to determine policy actions based on query results.

Scripts are typically written in shell scripting languages like Bash, but other languages (e.g., Python) can also be used, provided they interact correctly with Ridgeback's database.

Best Practices for Scripting Policies

• Start Simple: Begin with straightforward queries and gradually introduce complexity.
• Modularize Scripts: Reuse common functions or templates to simplify script maintenance.
• Test Thoroughly: Run scripts in a controlled environment before deploying them to production.
• Secure Your Scripts: Use environment variables (e.g., .env files) to manage sensitive information like database credentials.

Here is an example of a shell script (for Linux or Mac) that will list the MAC addresses of devices that joined the network within the last 24 hours:

#!/bin/bash
# Copyright (C)2022-2023 Ridgeback Network Defense, Inc.
#
# This query makes a good trigger statement.
# List the new MAC addresses
# over the last 24 hours.
#
source .env

ORGID=$1
ORG=Data_`echo ${ORGID} | tr '-' '_'`

if [ "$ORGID" == "" ] ; then
    echo "List the new MAC addresses"
    echo "over the last 24 hours."
    echo "  Usage: trigger-list-new-mac-24.sh <orgid>"
    exit 0
fi

sql="
    SELECT DISTINCT src_mac AS NewMacAddress
    FROM ${ORG}.NetEvent
    WHERE (
        ( time > ( now() - interval 24 hour ) ) AND
        ( src_sim IS NULL ) AND
        src_mac NOT IN (
            SELECT DISTINCT src_mac
            FROM ${ORG}.NetEvent
            WHERE (
                ( time > ( now() - interval 48 hour ) ) AND
                ( time < ( now() - interval 24 hour ) ) AND
                ( src_mac IS NOT NULL ) AND
                ( src_sim IS NULL )
            )
        )
    );
"

echo ${sql} | \
    mysql \
        --ssl \
        -h${DatabaseHostname} \
        -u${DatabaseUser} \
        -p${DatabasePassword}

Here is one that lists the MAC addresses that map to more than a single IP address:

#!/bin/bash
# Copyright (C)2022-2023 Ridgeback Network Defense, Inc.
#
# This query makes a good trigger statement.
# List the MAC addresses mapped to more than one IPv4 address
# over the last 24 hours.
#
source .env

ORGID=$1
ORG=Data_`echo ${ORGID} | tr '-' '_'`

if [ "$ORGID" == "" ] ; then
    echo "List the MAC addresses mapped to more than one IPv4 address"
    echo "over the last 24 hours."
    echo "  Usage: trigger-list-single-mac-many-ip4-24.sh <orgid>"
    exit 0
fi

sql="
    SELECT MacAddress, n
    FROM (
        SELECT src_mac AS MacAddress, COUNT(src_ip) AS n
        FROM (
            SELECT DISTINCT src_mac, src_ip
            FROM ${ORG}.NetEvent
            WHERE (
                ( time > ( now() - interval 24 hour ) ) AND
                ( src_ip != \"000.000.000.000\" ) AND
                ( src_ip != \"0.0.0.0\" ) AND
                ( src_ip IS NOT NULL) AND
                ( src_sim IS NULL )
            )
        ) AS t1
        GROUP BY src_mac
    ) AS t2
    WHERE
        ( n > 1 );
"

echo ${sql} | \
mysql \
    --ssl \
    -h${DatabaseHostname} \
    -u${DatabaseUser} \
    -p${DatabasePassword}