Deepfence YaraHunter Documentation

Deepfence YaraHunter is a malware scanner designed to find indicators of compromise (IOCs) in container images, running Docker containers, and filesystems. It utilizes a YARA ruleset to identify resources matching known malware signatures.

Use Cases:

• Build-and-test: Scan build artifacts in CI/CD pipelines.
• At rest: Scan local container images before deployment.
• At runtime: Scan running Docker containers to detect unusual activity.
• Filesystems: Scan local filesystems for indicators of compromise.

Key Features:

• Highly portable via a Docker container form factor.
• Designed for automation with easy-to-parse JSON output.

YaraHunter is designed for multiple security workflows:

• Build-and-test: Scan build artifacts within CI/CD pipelines to detect malware before deployment.
• At rest: Scan local container images before they are deployed to verify integrity.
• At runtime: Scan running Docker containers to detect compromises (e.g., in response to unusual network or CPU activity).
• Filesystems: Scan local filesystems at any time for indicators of compromise.

To start a local development server, use the yarn start command. This will open a browser window and support live reloading for most changes. By default, the server runs on port 3000. You can specify a different port using the --port flag.

$ yarn start

To scan a container that is currently running, you must mount the host's root directory into the YaraHunter container at a chosen location (e.g., /deepfence/mnt). You must then provide the --host-mount-path (the path inside the YaraHunter container) and the --container-id of the target running container.

docker run -it --rm --name=yara-hunter \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /:/deepfence/mnt \
    quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8 \
    --host-mount-path /deepfence/mnt --container-id 69221b948a73

To programmatically process scan results, use the --output=json flag and redirect the container's stdout to a file. You can also mount a local directory to /home/deepfence/output inside the container to persist output files.

Once you have the JSON output, you can use jq to extract specific fields, such as the Matched Rule Name from the IOC array.

docker run -i --rm --name=yara-hunter \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /tmp:/home/deepfence/output \
    quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8 \
    --image-name node:latest \
    --output=json > node-latest.json

cat /tmp/node-latest.json | jq '.IOC[] | ."Matched Rule Name"'

Instead of building from source, you can pull the official pre-built Docker image from the Quay.io registry.

docker pull quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8

You can scan container images for indicators of compromise (IOCs) by running the YaraHunter Docker container. To scan an image, provide the --image-name argument and specify the output format using --output=json.

To ensure the scanner can access the Docker daemon, you must mount /var/run/docker.sock. To save the results to your host machine, mount a local directory to /home/deepfence/output inside the container.

docker run -i --rm --name=deepfence-yarahunter \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /tmp:/home/deepfence/output \
     quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8 \
     --image-name metal3d/xmrig:latest \
     --output=json > xmrig-scan.json

To use YaraHunter via gRPC, you must first run the MalwareScanner service as a persistent server. This can be done using Docker by mounting the Docker socket and a specific socket path for communication.

Note: Ensure you provide a -socket-path argument to define where the Unix domain socket will be created.

docker run -it --rm --name=deepfence-malwarescanner \
	-v $(pwd):/home/deepfence/output \
	-v /var/run/docker.sock:/var/run/docker.sock \
	-v /tmp/sock:/tmp/sock \
	quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8 \
	-socket-path /tmp/sock/s.sock

You can pull the official YaraHunter image from Quay.io or build it from the source repository.

Pulling the image:

docker pull quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8

Building from source: Clone the repository and run:

make docker

To scan a container image, run the YaraHunter Docker container. You must mount the Docker socket to allow the scanner to interact with the Docker daemon and mount a local directory for output storage.

Basic Scan Command: Use the --image-name flag to specify the target image and --output=json to generate machine-readable results.

Scanning with cached rules: To speed up subsequent runs, you can mount a directory containing YARA rules and provide the path using the --rules-path argument.

Note: To get human-readable table formatted output instead of JSON, omit the --output=json flag.

docker run -i --rm --name=deepfence-yarahunter \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /tmp:/home/deepfence/output \
     quay.io/deepfenceio/deepfence_malware_scanner_ce:2.5.8 \
     --image-name metal3d/xmrig:latest \
     --output=json > xmrig-scan.json