Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction to Policy Triggers

Triggers are the foundation of Ridgeback's policy engine, serving as the mechanism for detecting specific network events or conditions. A trigger is essentially a SQL query that monitors network traffic, device behavior, or other defined criteria. When the conditions of a trigger are met, Ridgeback policies can respond with appropriate actions, such as generating alerts, logging activity, or taking automated remediation steps.

Why Use Triggers?

Triggers are powerful tools for network defense because they:

  • Monitor Critical Events: Identify unusual or unauthorized behavior, such as devices joining the network or multiple phantoms being contacted.
  • Automate Responses: Work seamlessly with policies to take action when specific conditions occur.
  • Customize Security: Tailor detection and response to meet the unique requirements of your organization.

How Triggers Work

  1. SQL Query-Based Detection: Each trigger is defined by a SQL query that extracts specific information from Ridgeback’s data sources. These queries are tailored to look for patterns, anomalies, or specific network events.
  2. Event-Driven Execution: Triggers evaluate data continuously or periodically, depending on the use case, and activate policies when conditions are met.
  3. Integration with Policies: Triggers are used as building blocks for Ridgeback policies, providing the logic needed to determine when a policy should take effect.

Writing Effective Triggers

When writing trigger queries, consider the following:

  • Focus on Key Indicators: Identify the critical events or behaviors you want to monitor.
  • Use Clear Criteria: Ensure that your SQL query accurately captures the conditions of interest without unnecessary complexity.
  • Test Queries Thoroughly: Run triggers in a test environment to verify their accuracy and performance before deployment.

Example Use Cases

Below are examples of common triggers:

  • Phantom Contact: Detect when a single host interacts with multiple phantoms within a short time frame.
  • Device Joining the Network: Identify when new devices connect to specific networks.

These examples, along with production and experimental queries provided later in this chapter, demonstrate the versatility of triggers in implementing robust network policies.

Sample Policy Triggers

Phantom Contact

  • "when any single host touches three or more phantoms in a ten minute window"

SELECT
    "Called 3+ phantoms within the last 10 minutes." AS Reason,
    CoreLabel AS Segment,
    src_ip AS LiveIpv4Address
FROM NetEvent
JOIN Core AS Core
	ON NetEvent.CoreId = Core.CoreId
WHERE
  src_ip IS NOT NULL AND
  dst_ip IS NOT NULL AND
  src_sim IS NULL AND
  dst_sim IS NOT NULL AND
  time > DATE_SUB(NOW(), INTERVAL 10 MINUTE)
GROUP BY Segment, src_ip
HAVING COUNT(DISTINCT dst_ip) >= 3;
-- Returns a list of endpoints that have contacted at least three phantoms in the last 10 minutes.

Device Joining a Network

  • "when a new device is added to specific networks"

SELECT distinct
	"New device join." AS Reason,
    CoreLabel AS Segment,
    src_mac AS NewMacAddress,
    src_ip AS NewIpv4Address
FROM NetEvent
JOIN Core AS Core
	ON NetEvent.CoreId = Core.CoreId
WHERE
  ( time >= ( NOW() - INTERVAL 10 MINUTE ) ) AND
  ( src_ip IS NOT NULL ) AND
  ( src_ip != "000.000.000.000" ) AND
  ( src_ip != "0.0.0.0" ) AND
  ( src_sim IS NULL ) AND
  src_mac NOT IN (
    SELECT DISTINCT src_mac
    FROM NetEvent
    WHERE
      ( time > ( NOW() - INTERVAL 10 * 2 MINUTE ) ) AND
      ( time < ( NOW() - INTERVAL 10 MINUTE ) ) AND
      ( src_mac IS NOT NULL ) AND
      ( src_sim IS NULL )
  );

-- Returns a list of new devices that have joined within the last 10 minutes.
-- Change the three instances of 10 to be what you want.

Older Stuff Below

  • Note! If copying and pasting into the Policy Trigger Query Management page be sure to NOT copy the remarks at that start of queries. The query gets formated as one line, and everything after the -- will be treated as a comment. The result of starting with a --explanation of the query
    is that the whole SQL query gets commented out and doesn't do anything.

Production Trigger Queries

-- --------------------------
-- PRODUCTION TRIGGER QUERIES
-- --------------------------

-- MAC addresses mapped to more than one IPv4 address (or IPv4 changed)
-- over the last 24 hours
SELECT MacAddress, n
FROM (
    SELECT src_mac AS MacAddress, COUNT(src_ip) AS n
    FROM (
        SELECT DISTINCT src_mac, src_ip
        FROM 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 );

-- IPv4 addresses mapped to more than one MAC address (or MAC changed)
-- over the last 24 hours
SELECT Ipv4Address, n
FROM (
    SELECT src_ip AS Ipv4Address, COUNT(src_mac) AS n
    FROM (
        SELECT DISTINCT src_mac, src_ip
        FROM 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_ip
) AS t2
WHERE
    ( n > 1 );


-- New MAC addresses seen in the last 24 hours
SELECT DISTINCT src_mac AS NewMacAddress
FROM NetEvent
WHERE (
    ( time > ( now() - interval 24 hour ) ) AND
    ( src_sim IS NULL ) AND
    src_mac NOT IN (
        SELECT DISTINCT src_mac
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 48 hour ) ) AND
            ( time < ( now() - interval 24 hour ) ) AND
            ( src_sim IS NULL )
        )
    )
);

-- New IPv4 addresses seen in the last 24 hours
SELECT DISTINCT src_ip AS NewIpv4Address
FROM 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 ) AND
    src_ip NOT IN (
        SELECT DISTINCT src_ip
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 48 hour ) ) AND
            ( time < ( now() - interval 24 hour ) ) AND
            ( src_sim IS NULL )
        )
    )
);

-- MAC addresses that disappeared in the last 24 hours
SELECT DISTINCT src_mac AS NewMacAddress
FROM NetEvent
WHERE (
    ( time > ( now() - interval 48 hour ) ) AND
    ( time < ( now() - interval 24 hour ) ) AND
    ( src_sim IS NULL ) AND
    src_mac NOT IN (
        SELECT DISTINCT src_mac
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 24 hour ) ) AND
            ( src_sim IS NULL )
        )
    )
);

-- IPv4 addresses that disappeared in the last 24 hours
SELECT DISTINCT src_ip AS NewIpv4Address
FROM NetEvent
WHERE (
    ( time > ( now() - interval 48 hour ) ) AND
    ( 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 ) AND
    src_ip NOT IN (
        SELECT DISTINCT src_ip
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 24 hour ) ) AND
            ( src_sim IS NULL )
        )
    )
);

Experimental Trigger Queries

-- -----------
-- EXPERIMENTS
-- -----------

-- Distinct, live src_mac/src_ip, sorted by src_ip
SELECT DISTINCT src_mac, src_ip
FROM NetEvent
WHERE time > '2022-04-22' AND time < '2022-04-23' AND src_ip != "000.000.000.000" AND src_sim IS NULL
ORDER BY src_ip;

-- Distinct, live src_mac/src_ip, sorted by src_mac
SELECT DISTINCT src_mac, src_ip
FROM NetEvent
WHERE time > '2022-04-22' AND time < '2022-04-23' AND src_ip != "000.000.000.000" AND src_sim IS NULL
ORDER BY src_mac;

-- MAC addresses mapped to more than one IP address (or IP changed)
SELECT MacAddress, n
FROM (
    SELECT src_mac AS MacAddress, COUNT(src_ip) AS n
    FROM (
        SELECT DISTINCT src_mac, src_ip
        FROM NetEvent
        WHERE time > '2022-04-22' AND time < '2022-04-23' AND src_ip != "000.000.000.000" AND src_sim IS NULL) AS t1
    GROUP BY src_mac
) AS t2
WHERE n > 1;

-- IP addresses mapped to more than one MAC addresses (or MAC changed)
SELECT Ipv4Address, n
FROM (
    SELECT src_ip AS Ipv4Address, COUNT(src_mac) AS n
    FROM (
        SELECT DISTINCT src_mac, src_ip
        FROM NetEvent
        WHERE time > '2022-04-22' AND time < '2022-04-23' AND src_ip != "000.000.000.000" AND src_sim IS NULL) AS t1
    GROUP BY src_ip
) AS t2
WHERE n > 1;


-- New IP addresses in second day.
SELECT DISTINCT src_ip AS NewIpAddress
FROM NetEvent
WHERE time > '2022-04-22' AND time < '2022-04-23' AND src_ip != "000.000.000.000" AND src_sim IS NULL AND src_ip NOT IN (
    SELECT DISTINCT src_ip
    FROM NetEvent
    WHERE time > '2022-04-21' AND time < '2022-04-22' AND src_ip != "000.000.000.000" AND src_sim IS NULL)
;

-- New MAC addresses in second day.
SELECT DISTINCT src_mac AS NewMacAddress
FROM NetEvent
WHERE time > '2022-04-22' AND time < '2022-04-23' AND src_sim IS NULL AND src_mac NOT IN (
    SELECT DISTINCT src_mac
    FROM NetEvent
    WHERE time > '2022-04-21' AND time < '2022-04-22' AND src_sim IS NULL)
;

-- --------------------------
-- PRODUCTION TRIGGER QUERIES
-- --------------------------

-- MAC addresses mapped to more than one IP address (or IP changed)
SELECT MacAddress, n
FROM (
    SELECT src_mac AS MacAddress, COUNT(src_ip) AS n
    FROM (
        SELECT DISTINCT src_mac, src_ip
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 24 hour ) ) AND
            ( src_ip != "000.000.000.000" ) AND
            ( src_ip != "0.0.0.0" ) AND
            ( src_sim IS NULL )
        )
    ) AS t1
    GROUP BY src_mac
) AS t2
WHERE
    ( n > 1 );

-- IP addresses mapped to more than one MAC addresses (or MAC changed)
SELECT Ipv4Address, n
FROM (
    SELECT src_ip AS Ipv4Address, COUNT(src_mac) AS n
    FROM (
        SELECT DISTINCT src_mac, src_ip
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 24 hour ) ) AND
            ( src_ip != "000.000.000.000" ) AND
            ( src_ip != "0.0.0.0" ) AND
            ( src_sim IS NULL )
        )
    ) AS t1
    GROUP BY src_ip
) AS t2
WHERE
    ( n > 1 );


-- New MAC addresses seen in last 24 hours.
SELECT DISTINCT src_mac AS NewMacAddress
FROM NetEvent
WHERE (
    ( time > ( now() - interval 24 hour ) ) AND
    ( src_sim IS NULL ) AND
    src_mac NOT IN (
        SELECT DISTINCT src_mac
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 48 hour ) ) AND
            ( time < ( now() - interval 24 hour ) ) AND
            ( src_sim IS NULL )
        )
    )
);

-- New IP addresses seen in last 24 hours.
SELECT DISTINCT src_ip AS NewIpAddress
FROM NetEvent
WHERE (
    ( time > ( now() - interval 24 hour ) ) AND
    ( src_sim IS NULL ) AND
    src_ip NOT IN (
        SELECT DISTINCT src_ip
        FROM NetEvent
        WHERE (
            ( time > ( now() - interval 48 hour ) ) AND
            ( time < ( now() - interval 24 hour ) ) AND
            ( src_sim IS NULL )
        )
    )
);

-- Blackholes seen in the last 24 hours.
SELECT 
    a.src_ip, 
    a.dst_ip,
    COUNT(a.time) AS count,
    MIN(a.time) AS firstSeen,
    MAX(a.time) AS lastSeen
FROM 
    NetEvent a
LEFT JOIN (
    SELECT DISTINCT 
        src_ip 
    FROM 
        NetEvent 
    WHERE 
        proto = 'arp' 
        AND src_ip IS NOT NULL 
        AND time > DATE_SUB(NOW(), INTERVAL 25 HOUR)
) b 
ON 
    b.src_ip = a.dst_ip
WHERE 
    b.src_ip IS NULL 
    AND time > DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY 
    a.dst_ip;