Scan Files with YARA Rules

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

Rely on cnspec and YARA rules to detect malware signatures, exposed secrets, and custom patterns in files across your systems. cnspec includes 40+ built-in YARA rules for detecting common secrets like AWS credentials, GitHub tokens, and private keys. You can also write custom rules for any pattern you need to find.

Before you begin

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

The YARA provider currently supports scanning local files only.

Scan for secrets with policy-based scanning

You can create cnspec policies that use YARA rules to scan for secrets and malware indicators. For example, this policy checks that no AWS credentials exist in common locations:

policies:
  - uid: secret-policy
    name: Secret Detection
    require:
      - provider: os
      - provider: yara
    groups:
      - title: AWS Secrets
        filters: asset.platform == "macos" || asset.platform == "linux"
        checks:
          - uid: aws-secrets-check
            title: Ensure no static AWS secrets in .aws directory
            mql: |
              files.find(from: "/Users", type: "file", regex: '.*\.aws.*', depth: 3)
              {
                yara.scan(path: path, rulesets: ["secrets_aws_credentials"]).result == empty
              }

To scan using a policy file:

cnspec scan --policy-bundle secret-policy.mql.yaml

You can also create your own policies that combine YARA scanning with other cnspec checks.

Explore YARA scanning

Run cnspec shell to open the interactive shell. The YARA provider loads automatically alongside the os provider.

Scan a file

Scan a file against all built-in YARA rules:

cnspec> 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:

cnspec> 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"
]

Scan with a specific rule

Scan using only specific rule identifiers:

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

View match details

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

cnspec> 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 custom inline rule

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

cnspec> 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:

cnspec> 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 }

Example security checks

Ensure a file contains no secrets

Check that a specific file has no matches against all built-in secret detection rules:

cnspec> yara.scan(path: "/path/to/file").result == empty
[ok] value: true

Ensure a file contains no AWS credentials

Check a file against a specific ruleset:

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

Explore available rulesets

List all rulesets

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

cnspec> 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

cnspec> yara.rulesets.builtIn

View rules in a specific ruleset

cnspec> 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

cnspec> 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/

cnspec 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 cnspec 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.

Scan Files with YARA Rules

On this page