Query Files with YARA Rules

Scan files for malware, secrets, and custom patterns using YARA rules with cnquery

Mondoo's yara provider lets you use cnquery to scan files for malware signatures, exposed secrets, and custom patterns using YARA rules. You can use built-in rulesets for common detections like AWS credentials and API tokens, or write your own rules for any pattern you need to find.

Requirements

To scan files with YARA rules using cnquery, you must have:

cnquery installed on your workstation
Files to scan on your local machine

The YARA provider currently supports scanning local files only.

Connect to your local environment

To open a cnquery shell with YARA scanning capabilities:

cnquery shell

The YARA provider loads automatically as a supporting provider alongside the os provider. There's no separate connection step.

Example queries

Scan a file

Scan a file against all built-in YARA rules:

cnquery> yara.scan(path: "/path/to/file").result
yara.scan.result: [
  0: yara.matchRule rule="secrets_aws_credentials" namespace="secrets_aws_credentials"
]

Scan with a specific ruleset

Scan a file using only a specific ruleset:

cnquery> yara.scan(path: "/Users/stella/.aws/credentials", rulesets: ["secrets_aws_credentials"]).result
yara.scan.result: [
  0: yara.matchRule rule="secrets_aws_credentials" namespace="secrets_aws_credentials"
]

View match details

Retrieve full details about matches, including what strings matched and where:

cnquery> yara.scan(path: "/path/to/file", rulesets: ["secrets_aws_credentials"]).result { rule tags meta strings }
yara.scan.result: [
  0: {
    rule: "secrets_aws_credentials"
    tags: []
    meta: {
      description: "Detects strings resembling AWS Access Keys and Secret Keys"
      severity: "critical"
      credential_type: "aws"
    }
    strings: [
      0: yara.matchString name="$access_key" offset=42 length=20
    ]
  }
]

Scan with a specific rule

Scan using only specific rule identifiers:

cnquery> yara.scan(path: "/path/to/file", rules: ["secrets_aws_credentials"]).result

Scan with a custom inline rule

Write a custom YARA rule inline to scan for any pattern:

cnquery> yara.scan(path: "/path/to/file", source: 'rule find_password { strings: $s = "password" condition: $s }').result
yara.scan.result: [
  0: yara.matchRule rule="find_password" namespace="default"
]

Search for secrets across files

Combine with the files resource to scan multiple files for exposed secrets:

cnquery> files.find(from: "/Users", type: "file", regex: '.*\.aws.*', depth: 3).where(yara.scan(path: path, rulesets: ["secrets_aws_credentials"]).result != empty) { path yara.scan(path: path, rulesets: ["secrets_aws_credentials"]).result }

Explore available rulesets

List all rulesets

See all loaded rulesets, including built-in and custom rules:

cnquery> yara.rulesets.list
yara.rulesets.list: [
  0: yara.ruleset name="secrets_aws_credentials" origin="builtin"
  1: yara.ruleset name="secrets_github_token" origin="builtin"
  2: yara.ruleset name="secrets_private_key" origin="builtin"
  ...
]

List built-in rulesets only

cnquery> yara.rulesets.builtIn

View rules in a specific ruleset

cnquery> yara.ruleset("secrets_aws_credentials").rules { identifier description author score }
yara.ruleset.rules: [
  0: {
    identifier: "secrets_aws_credentials"
    description: "Detects strings resembling AWS Access Keys and Secret Keys"
    author: "Mondoo"
    score: 0
  }
]

List all rules across all rulesets

cnquery> yara.rules { identifier description }

Built-in secret detection rules

The YARA provider includes 40+ built-in rules for detecting exposed secrets:

Ruleset	Detects
`secrets_aws_credentials`	AWS access keys and secret keys
`secrets_github_token`	GitHub personal access tokens
`secrets_gitlab_token`	GitLab tokens
`secrets_gcp_credentials`	GCP service account credentials
`secrets_azure_credentials`	Azure credentials
`secrets_private_key`	PEM and SSH private keys
`secrets_docker_credentials`	Docker registry credentials
`secrets_kubernetes_token`	Kubernetes service account tokens
`secrets_slack_token`	Slack API tokens
`secrets_okta_token`	Okta API tokens
`secrets_stripe_key`	Stripe API keys
`secrets_twilio_key`	Twilio API keys
`secrets_database_connection_string`	Database connection strings
`secrets_jwt_token`	JSON Web Tokens

Add custom YARA rules

To add your own YARA rules, place .yar files in:

~/.config/mondoo/yara/rules/

cnquery automatically loads custom rules from this directory alongside the built-in rules.

For example, create ~/.config/mondoo/yara/rules/my-rules.yar:

rule detect_malware_string {
    meta:
        description = "Detects a known malware indicator"
        severity = "high"

    strings:
        $indicator = "malicious_payload"

    condition:
        $indicator
}

After adding the file, the rule is available immediately in your next cnquery session.

Learn more

To learn more about how the MQL query language works, read Write Effective MQL.
To learn about writing YARA rules, read the YARA documentation.

Query Files with YARA Rules

On this page