Build Custom Detector

This guide walks you through building your custom detector on the Venn Network. Use this as a starting point to implement your detection logic which will secure transactions on the Venn Network.

This guide is intended for developers, security researchers, and security teams who want to integrate their unique threat models into the Venn ecosystem or develop new security models.

Overview

To build a custom detector on Venn, you will need to:

1. Clone (or fork) venn-custom-detection Template.

2. Implement your detection logic.

3. Test that your detector responds with detection results.

4. Deploy your detector and connect it to your Venn node client.

You can choose to become a Venn node operator and run your detection model on your node, or connect with other Venn node operators that will run your detection model.

If you need help connecting with a Venn node operator to run your detector, please contact us. We’re here to help you find a trusted partner so you can deploy your detection model.

---

Quick Start

Step 1: Clone the Repository

Begin by cloning or forking the Venn Custom Detector Boilerplate.

git clone https://github.com/ironblocks/venn-custom-detection.git
cd venn-custom-detection

Step 2: Install Dependencies

Install the required packages using your preferred package manager:

yarn install
# or
npm install

Step 3: Run in Development Mode

Start the detector locally to begin working on your detection logic:

yarn dev
# or
npm run dev

Your detector service will start (default on port 3000) and be ready to receive detection requests.

---

Detector Service Overview

The core of your custom detector logic is the DetectionService, found in src/modules/detection-module/service.ts. This service implements a detect method that receives a DetectionRequest (an enriched view of an EVM transaction) and returns a DetectionResponse.

Example Implementation

import { DetectionResponse, DetectionRequest } from './dtos'

/**
 * DetectionService
 *
 * Implements a `detect` method that receives an enriched view of an
 * EVM compatible transaction (i.e. `DetectionRequest`)
 * and returns a `DetectionResponse`
 *
 * API Reference:
 * https://github.com/ironblocks/venn-custom-detection/blob/master/docs/requests-responses.docs.md
 */
export class DetectionService {
    /**
     * Update this implementation code to insepct the `DetectionRequest`
     * based on your custom business logic
     */
    public static detect(request: DetectionRequest): DetectionResponse {
        
        /**
         * For this "Hello World" style boilerplate
         * we're mocking detection results using
         * some random value
         */
        const detectionResult = Math.random() < 0.5;


        /**
         * Wrap our response in a `DetectionResponse` object
         */
        return new DetectionResponse({
            request,
            detectionInfo: {
                detected: detectionResult,
            },
        });
    }
}

Update the detect method with your security logic or model to analyze transactions based on your threat model.

For more details, request validation, and response structures, refer to our API Reference Documentation.

---

Testing Your Detector

You can simulate transactions using the Security Sandbox, a dedicated testing environment specifically designed to evaluate your custom detection model. With the Security Sandbox, you can simulate any transactions from the preferred chains or choose past hacks to test against your detection model.

Or

You can simulate transactions by sending them directly to DetectionRequest payload (refer to our API Reference for details) and evaluate your custom detection model in the returned DetectionResponse.

---

Deploy to Production

When you’re ready to deploy your detector service, choose from one of the following options:

Manual Build & Deployment

1. Build the Service:

   yarn build
   # or
   npm run build

2. Start the Service:

   yarn start
   # or
   npm run start

Using Docker

Build a Docker image for your detector:

docker build -f Dockerfile . -t my-custom-detector

Deploy the Docker container to your production environment as needed.

That's it! Welcome to Venn. 🎉