Scan Files with YARA Rules and cnspec

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

Detect malware signatures, exposed secrets, and custom patterns in files across your systems with cnspec and YARA-X. cnspec ships 30+ built-in YARA rules for common secrets like AWS credentials, GitHub tokens, and private keys, and you can write custom rules for any pattern you need to find.

New to cnspec? Start with the quickstart.

Prerequisites

cnspec installed on your workstation
Files to scan on your local machine or on a remote host you can reach over SSH

The YARA provider scans files on the local machine and on remote hosts that cnspec connects to over SSH (cnspec scan ssh user@HOST). Other connection types are not supported.

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
    version: 1.0.0
    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: rule="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: rule="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: lineNumber=2 data="AKIAIOSFODNN7EXAMPLE"
    ]
  }
]

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: rule="find_password"
]

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: []

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
  expected: == _
  actual:   [
    0: default/secrets_aws_credentials/3JmmF4R6wtHv8hPdEgZC2jyHnJc
  ]

Explore available rulesets

List all rulesets

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

cnspec> yara.rulesets.list
yara.rulesets.list: [
  0: name="secrets_asana_tokens"
  1: name="secrets_atlassian_tokens"
  2: name="secrets_aws_credentials"
  ...
]

List built-in rulesets only

cnspec> yara.rulesets.builtIn

View rules in a specific ruleset

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

List all rules across all rulesets

cnspec> yara.rulesets { name rules { identifier description } }

Built-in secret detection rules

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

Ruleset	Detects
`secrets_aws_credentials`	AWS access keys and secret keys
`secrets_github_tokens`	GitHub personal access tokens
`secrets_gitlab_tokens`	GitLab tokens
`secrets_gcp_credentials`	GCP service account credentials
`secrets_azure_credentials`	Azure credentials
`secrets_private_keys_pem`	PEM-encoded private keys
`secrets_ssh_private_keys`	SSH private keys
`secrets_docker_credentials`	Docker registry credentials
`secrets_kubernetes_tokens`	Kubernetes service account tokens
`secrets_slack_tokens`	Slack API tokens
`secrets_okta_tokens`	Okta API tokens
`secrets_stripe_keys`	Stripe API keys
`secrets_twilio_credentials`	Twilio Account SID and Auth Token
`secrets_database_connection_strings`	Database connection strings
`secrets_jwt_tokens`	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.

Go further with Mondoo Platform

To continuously scan for malware across your fleet and track results over time, register cnspec with Mondoo Platform.

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

On this page