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.

Example checks

Run cnspec shell to open the cnspec interactive shell. From there you can make checks like the examples below.

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

View match details

When a check fails, drill into the match details to understand what was found:

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 check for any pattern:

cnspec> yara.scan(path: "/path/to/file", source: 'rule find_password { strings: $s = "password" condition: $s }').result == empty
[ok] value: true

Search for secrets across multiple files

Combine with the files resource to check multiple files:

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 }

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

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