Fixing Wazuh SCA Scan Failures: Adding Shell Wrappers to Command Rules

Wazuh Security Configuration Assessment (SCA) is one of the platform’s most valuable compliance and hardening features.

It allows organizations to continuously evaluate systems against security benchmarks such as CIS controls, internal security baselines, and regulatory requirements.

Rather than relying on periodic manual audits, SCA automatically verifies whether endpoints comply with predefined security policies and reports any deviations.

A key capability within SCA policies is the ability to perform command-based checks. These checks execute operating system commands and evaluate the output against expected values.

Administrators commonly use them to validate running services, kernel parameters, package configurations, account settings, and other security-related controls that cannot easily be verified through simple file or registry inspections.

However, many Wazuh administrators eventually encounter a frustrating issue: SCA command rules fail even though the command works perfectly when executed manually from a terminal session.

In many cases, the root cause is that the command depends on shell functionality such as pipes (|), redirection (>), variable expansion ($VAR), command chaining (&&), or subshell execution.

Since Wazuh does not automatically execute commands through a shell interpreter, these checks can fail unexpectedly when no shell wrapper is used.

The consequences can be significant. Failed command rules may generate false negatives, causing compliant systems to appear non-compliant.

Security teams may spend hours troubleshooting benchmark failures, while auditors receive inaccurate compliance reports that do not reflect the true security posture of monitored systems.

In this guide, you’ll learn how Wazuh executes SCA command rules, why shell wrappers are often required, how to identify wrapper-related failures, and how to properly modify SCA policies so command-based assessments execute reliably and produce accurate compliance results.

Understanding How Wazuh SCA Executes Command Rules

What Are SCA Command Rules?

Security Configuration Assessment policies consist of multiple rule types that validate different aspects of a system’s configuration.

Among these rule types, command-based checks are the most flexible because they allow administrators to gather information directly from operating system commands.

The primary purpose of command checks is to validate settings that cannot easily be verified through static file inspection alone. Examples include:

Verifying active services
Checking kernel runtime parameters
Validating user account configurations
Confirming package installation status
Inspecting command output for security settings

SCA policies support several different check mechanisms:

Check Type	Purpose
File Checks	Validate file existence, permissions, ownership, and contents
Registry Checks	Verify Windows registry settings
Package Checks	Confirm package installation status
Command Checks	Execute commands and evaluate their output

For example, an SCA policy might use a command check to verify whether SSH root login is disabled:

c:grep "^PermitRootLogin" /etc/ssh/sshd_config

Or validate kernel security settings:

c:sysctl net.ipv4.ip_forward

Command rules are heavily used throughout many compliance benchmarks because they provide dynamic visibility into the current operating state of the system.

For additional guidance on validating custom detections and command outputs, see our guide: How to Test Wazuh Rules.

How Wazuh Executes Commands During SCA Scans

Understanding the execution model is essential when troubleshooting command failures.

During an SCA scan, the Wazuh agent processes each policy item sequentially.

When a command rule is encountered, the SCA engine launches the specified executable and captures its output for evaluation against the rule conditions.

The workflow typically follows these steps:

Load the SCA policy.
Parse the command rule.
Execute the command.
Capture stdout and stderr.
Compare results against policy requirements.
Mark the control as passed, failed, or not applicable.

Unlike an interactive terminal session, however, SCA commands run inside a controlled execution environment designed to reduce security risks.

This behavior is documented by the official Wazuh SCA Documentation.

Several important limitations exist:

No interactive shell session is launched automatically.
Shell-specific syntax is not interpreted.
User profile scripts are not loaded.
Environment variables may differ from interactive sessions.
PATH definitions may be limited.
Command chaining behavior may not be available.

As a result, commands that work perfectly in Bash, Zsh, or PowerShell may behave differently when executed by the SCA engine.

Why Shell Wrappers Matter

A shell wrapper explicitly invokes a shell interpreter and passes the command string to that shell for processing.

For example:

Without wrapper:

c:grep sshd_config /etc/passwd | wc -l

With wrapper:

c:/bin/bash -c "grep sshd_config /etc/passwd | wc -l"

The difference is significant.

When Wazuh executes a command directly, it treats the command and its arguments literally. Special shell constructs are not interpreted. Characters such as:

Pipes (|)
Redirects (>, >>, <)
Variables ($HOME)
Command substitution ($(...))
Logical operators (&&, ||)
Wildcards (*)

require a shell interpreter to function correctly.

Shell wrappers instruct the operating system to process these features before returning the output to Wazuh.

Common situations where missing wrappers cause failures include:

Piped Commands

ps aux | grep sshd

Without a shell, the pipe operator is never processed.

Command Chaining

systemctl status sshd && echo running

The second command may never execute correctly.

Variable Expansion

echo $PATH

Environment variables may not resolve as expected.

Output Redirection

cat file.txt > output.txt

Redirection operators require shell interpretation.

According to the official Bash Reference Manual, shell interpreters are responsible for expansions, redirections, pipelines, and command substitution before a command is executed.

When Wazuh bypasses the shell, those features are unavailable unless explicitly invoked.

This behavior explains why many administrators see SCA controls fail despite successful manual testing from a terminal session.

Symptoms of Missing Shell Wrappers in SCA Policies

SCA Checks Consistently Return Failed

One of the earliest warning signs is a compliance control that continually reports a failed status despite the system clearly meeting the required configuration.

Administrators often verify the command manually and receive the expected output, yet Wazuh continues marking the control as non-compliant.

Typical symptoms include:

Persistent failed SCA controls
Unexpected benchmark score reductions
Compliance reports showing missing controls
Inconsistent results across systems

These failures are frequently false negatives caused by command execution problems rather than actual configuration issues.

Commands Work Manually but Fail in Wazuh

This is perhaps the strongest indicator that a shell wrapper is missing.

For example:

systemctl list-unit-files | grep sshd

works correctly when executed directly in a terminal.

However, when the same command is placed inside an SCA policy without a wrapper, Wazuh may fail to process the pipe operator, resulting in an empty output and a failed assessment.

Differences between interactive terminal sessions and SCA execution commonly involve:

Different environment variables
Reduced PATH definitions
Missing shell interpretation
Different execution permissions
Non-interactive execution contexts

The official POSIX Shell Command Language Specification explains that shell operators, expansions, and command processing occur before execution, reinforcing why direct command execution behaves differently from shell-based execution.

Compliance Controls Unexpectedly Show Non-Compliant

Shell-wrapper issues frequently appear during CIS benchmark deployments and internal compliance audits.

Examples include controls validating:

SSH hardening settings
Auditd configurations
Password policy enforcement
Kernel security parameters
Service startup configurations

When command execution fails, compliant systems may incorrectly appear non-compliant.

This can create several operational problems:

Inaccurate audit reports
Reduced benchmark scores
Unnecessary remediation efforts
Increased investigation workload
Loss of confidence in compliance metrics

If you’re troubleshooting broader SCA-related visibility issues, you may also find these guides useful:

SCA Scan Logs Show Command Execution Errors

Reviewing Wazuh logs often reveals clues pointing directly to command execution problems.

Common indicators include:

Empty command output
Unexpected command return codes
Parsing failures
Missing executable errors
Invalid argument messages

Depending on the operating system and policy design, administrators may observe log entries indicating that command output could not be generated or that the expected command syntax was not recognized.

Particularly suspicious situations include:

Commands containing pipes that return no data
Variable-based commands producing blank output
Multi-command sequences failing unexpectedly
Controls failing only within SCA scans

When these symptoms occur alongside successful manual command execution, the probability of a missing shell wrapper is extremely high.

As noted by experienced Wazuh community contributors and security engineers in numerous troubleshooting discussions, command execution context is one of the most commonly overlooked causes of SCA assessment failures.

Verifying how the command is launched is often the fastest path to resolution before investigating more complex policy or agent-level issues.

Common Root Causes

Pipes and Command Chaining Are Not Interpreted

The most common reason SCA command rules fail is that shell operators are never processed.

Many administrators write commands exactly as they would in a Linux terminal, assuming Wazuh will execute them through a shell. In reality, the SCA engine executes commands directly unless a shell wrapper is explicitly specified.

As a result, operators such as pipes (|), logical AND (&&), and logical OR (||) are treated as literal arguments instead of shell instructions.

grep Pipelines

Consider the following command:

grep PermitRootLogin /etc/ssh/sshd_config | grep no

In an interactive shell, the output from the first grep command is passed to the second command through the pipe operator.

Without a shell wrapper, the pipe is not interpreted, causing the command to fail or return unexpected output.

awk Processing

Many compliance checks use awk to extract fields from command output:

ps aux | awk '{print $1}'

Since the pipeline depends on shell processing, the command may not execute correctly when called directly by the SCA engine.

sed Transformations

Commands that perform text manipulation frequently combine utilities:

cat /etc/passwd | sed 's/:.*//'

Again, the pipe operator requires shell interpretation.

Multiple Commands Joined with && or ||

Conditional command execution is another frequent source of failures.

Example:

systemctl is-enabled sshd && echo enabled

test -f /etc/ssh/sshd_config || echo missing

Without a shell wrapper, the logical operators are not processed, causing the rule to fail even though the system is correctly configured.

Shell Variables Are Not Expanded

Another common issue occurs when commands rely on environment variables or shell expansion features.

Environment Variables

Consider:

echo $PATH

ls $HOME/.ssh

Variable expansion is performed by the shell before command execution. If no shell interpreter is present, the variable may remain unresolved.

This frequently affects custom SCA policies that reference:

$PATH
$HOME
$USER
$HOSTNAME
Custom application variables

Command Substitution Failures

Command substitution allows one command to use the output of another command.

Examples:

echo $(hostname)

grep $(whoami) /etc/passwd

Since command substitution is a shell feature, it will not work correctly without an explicit shell wrapper.

Output Redirection Fails

Many administrators assume output redirection will behave normally within SCA policies.

Redirect Operators Not Processed

Commands such as:

cat /etc/passwd > /tmp/output.txt

echo test >> /tmp/log.txt

depend on shell-managed redirection.

Without a shell interpreter, these operators are not processed as expected.

Temporary File Creation Issues

Some advanced compliance checks generate temporary files for analysis:

netstat -an > /tmp/netstat.out
grep LISTEN /tmp/netstat.out

If the redirection never occurs, subsequent commands fail because the expected temporary file does not exist.

Complex Commands Depend on Shell Features

The more sophisticated a command becomes, the more likely it depends on shell functionality.

Conditional Statements

Examples include:

if [ -f /etc/ssh/sshd_config ]; then echo yes; fi

Conditional logic requires a shell interpreter.

Loops

Loop constructs such as:

for user in $(cut -d: -f1 /etc/passwd); do
    echo $user
done

cannot execute correctly without a shell environment.

Nested Command Execution

Commands that combine multiple shell features often fail silently.

Example:

echo $(grep PermitRootLogin /etc/ssh/sshd_config | awk '{print $2}')

This command depends on:

Command substitution
Pipes
Variable expansion

Without a wrapper, none of these operations may function correctly.

When troubleshooting SCA failures, complex command syntax should always be considered a potential root cause.

How to Identify Affected SCA Rules

Review Existing SCA Policy Files

The first step is determining which controls use command-based checks.

On Linux systems, SCA policy files are commonly located in directories such as:

/var/ossec/ruleset/sca/

/var/ossec/etc/shared/

depending on your deployment model and custom policy structure.

The official Wazuh SCA documentation provides details on policy structure and syntax.

Finding Command-Based Checks

Within SCA policies, command checks typically begin with the c: prefix.

Examples:

c:systemctl is-enabled sshd

c:sysctl net.ipv4.ip_forward

c:grep PermitRootLogin /etc/ssh/sshd_config

Search policy files for:

grep -R "c:" /var/ossec/ruleset/sca/

This quickly identifies all command-based controls that may be affected.

Examine Command Syntax

After locating command rules, inspect the syntax carefully.

Identifying Shell-Dependent Constructs

Look for commands containing:

Pipes (|)
Redirects (>, >>, <)
Logical operators (&&, ||)
Environment variables ($HOME, $PATH)
Command substitution ($(...))
Wildcards (*)
Shell conditionals
Loops

Any of these may require a shell wrapper.

Recognizing Problematic Patterns

Examples of potentially problematic commands include:

grep sshd_config /etc/passwd | wc -l

echo $HOSTNAME

systemctl status sshd && echo running

echo $(hostname)

These patterns should be prioritized during troubleshooting.

Test Commands Outside of Wazuh

Once a potentially problematic command is identified, test it manually.

Verifying Expected Output

Run the command exactly as written:

grep PermitRootLogin /etc/ssh/sshd_config

Verify that:

Output is generated
Exit codes are correct
The expected compliance value appears

Comparing Execution Contexts

Next, compare the command with a wrapped version:

/bin/sh -c "grep PermitRootLogin /etc/ssh/sshd_config"

and

/bin/bash -c "grep PermitRootLogin /etc/ssh/sshd_config"

This comparison often reveals whether shell processing is required.

For additional troubleshooting techniques, see:

Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive

Although focused on decoders, many of the same validation principles apply when testing SCA command execution.

Use Wazuh Log Files for Troubleshooting

Wazuh logs frequently provide valuable clues about failed SCA checks.

Relevant Log Locations

Depending on your platform, review:

/var/ossec/logs/ossec.log

and agent-side logs where applicable.

You may also find useful diagnostic information within manager logs and SCA execution records.

Tracing Command Execution Failures

Look for indicators such as:

Command execution errors
Empty output results
Non-zero return codes
Parsing failures
SCA evaluation warnings

Useful search commands include:

grep -i sca /var/ossec/logs/ossec.log

and

grep -i command /var/ossec/logs/ossec.log

If logs show command failures while manual execution succeeds, shell-wrapper issues become a leading suspect.

For broader agent troubleshooting, see:

Wazuh Agent Not Connecting to Manager? 12 Proven Fixes

and

Wazuh Dashboard Not Loading? Complete Troubleshooting Guide

These articles provide additional techniques for collecting diagnostics across Wazuh deployments.

Fixing SCA Command Rules with Shell Wrappers

When to Use a Shell Wrapper

Not every SCA command requires a shell wrapper.

Simple commands generally work without one:

c:hostname

c:uname -r

c:systemctl is-enabled sshd

However, wrappers should be used whenever a command depends on shell functionality.

Decision Criteria

Use a wrapper if the command contains:

Pipes (|)
Redirection (>, >>, <)
Variables ($VAR)
Command substitution ($(...))
Conditional operators (&&, ||)
Shell loops
Shell conditionals

Common Use Cases

Typical examples include:

CIS benchmark checks
Auditd validation
SSH hardening verification
Package inventory filtering
Custom compliance controls

Using /bin/sh -c

The most portable approach is to execute commands through /bin/sh.

Syntax Examples

Example:

c:/bin/sh -c "grep PermitRootLogin /etc/ssh/sshd_config | grep no"

Another example:

c:/bin/sh -c "systemctl is-enabled sshd && echo enabled"

Best Practices

Keep commands simple and readable.
Use double quotes around the command string.
Avoid unnecessary nesting.
Validate commands manually before deployment.
Test policies on staging systems first.

Compatibility Considerations

/bin/sh provides the highest compatibility across Linux distributions.

For most compliance checks, it is the preferred wrapper because it minimizes dependency on a specific shell implementation.

Using /bin/bash -c

Some commands require functionality beyond what standard POSIX shells provide.

In these cases, Bash may be necessary.

When Bash-Specific Functionality Is Required

Examples include:

Arrays
Advanced string manipulation
Extended pattern matching
Bash-specific conditionals
Process substitution

Examples of Advanced Shell Features

Example:

c:/bin/bash -c "for user in ${users[@]}; do echo $user; done"

Example:

c:/bin/bash -c "diff <(sort file1) <(sort file2)"

Use Bash only when required because it reduces portability across systems.

Before-and-After Examples

Example 1: Pipe Processing

Original Failing Rule

c:grep PermitRootLogin /etc/ssh/sshd_config | grep no

Corrected Rule with Wrapper

c:/bin/sh -c "grep PermitRootLogin /etc/ssh/sshd_config | grep no"

Example 2: Multiple Commands

Original Failing Rule

c:systemctl is-enabled sshd && echo enabled

Corrected Rule with Wrapper

c:/bin/sh -c "systemctl is-enabled sshd && echo enabled"

Example 3: Variable Expansion

Original Failing Rule

c:echo $HOSTNAME

Corrected Rule with Wrapper

c:/bin/sh -c "echo $HOSTNAME"

Example 4: Command Substitution

Original Failing Rule

c:echo $(hostname)

Corrected Rule with Wrapper

c:/bin/sh -c "echo $(hostname)"

After implementing wrappers, rerun the SCA assessment and verify that controls transition from failed to passed status.

In many environments, this single change immediately restores accurate compliance reporting and eliminates large numbers of false-negative findings.

For additional configuration troubleshooting guidance, see:

Validating the Fix

After updating your SCA policies to use appropriate shell wrappers, it’s important to verify that the changes actually resolve the problem.

Validation ensures that your compliance reports accurately reflect the system’s security posture and that no new issues were introduced during the modification process.

A systematic validation process should include triggering a fresh assessment, reviewing the resulting compliance status, examining Wazuh logs, and comparing automated results against manual command execution.

Trigger a New SCA Scan

The first step is forcing Wazuh to perform a new Security Configuration Assessment using the updated policy.

Depending on your deployment, this can be accomplished by:

Restarting the Wazuh agent
Reloading the modified SCA policy
Waiting for the next scheduled SCA scan interval
Initiating a manual scan if your deployment supports it

Before running the assessment, verify that the updated policy file has been successfully deployed to the endpoint.

Methods for Running a Fresh Assessment

Common validation approaches include:

systemctl restart wazuh-agent

or, on systems using older service managers:

service wazuh-agent restart

After restarting the agent, allow sufficient time for the SCA module to reload policies and execute a new assessment.

If you manage many endpoints, consider testing the updated policy on a small subset of systems before deploying it organization-wide.

Confirming Policy Reloads

Verify that:

The modified SCA policy is present on the endpoint.
There are no syntax errors in the policy.
The Wazuh agent starts successfully.
The SCA module initializes without warnings.

If policy changes are not reflected after restarting the agent, double-check that the correct policy file was edited and distributed.

For additional policy validation guidance, see:

How to Test Wazuh Rules

Review SCA Results

Once the assessment completes, review the updated SCA results within the Wazuh Dashboard or your preferred reporting interface.

Verifying Successful Control Evaluation

Focus on the controls that previously failed due to command execution issues.

Ideally, they should now:

Execute without errors
Return the expected command output
Evaluate successfully against the policy conditions
Transition from Failed to Passed, where appropriate

If only a subset of controls continues to fail, inspect those commands individually to determine whether additional shell features or syntax adjustments are required.

Checking Compliance Status Updates

After successful execution, benchmark scores should update accordingly.

Verify that:

Compliance percentages increase as expected.
Previously affected CIS controls are marked compliant.
False-negative findings disappear.
Reports accurately reflect the system configuration.

Unexpected compliance changes should always be investigated before assuming the issue has been fully resolved.

Inspect Wazuh Logs

Logs provide the most reliable confirmation that the modified command is executing correctly.

Confirming Successful Command Execution

Review:

/var/ossec/logs/ossec.log

Search for entries related to SCA execution:

grep -i sca /var/ossec/logs/ossec.log

Successful execution generally results in:

No command execution errors
No parsing failures
Successful policy evaluation
Expected control status updates

Detecting Residual Issues

Continue monitoring for messages indicating:

Command failures
Invalid syntax
Permission problems
Missing executables
Timeout errors

If errors remain after adding a wrapper, investigate other potential causes such as incorrect file paths, insufficient permissions, or unsupported command syntax.

For broader troubleshooting techniques, see:

Wazuh Dashboard Not Loading? Complete Troubleshooting Guide

Compare Results Against Manual Testing

The final validation step is confirming that automated SCA execution produces the same outcome as manual command execution.

Ensuring Output Consistency

Run the wrapped command directly from a shell.

For example:

/bin/sh -c "grep PermitRootLogin /etc/ssh/sshd_config | grep no"

Compare the output with the value used by the SCA policy.

Both should produce identical results.

Eliminating False Negatives

Once manual execution and SCA evaluation match consistently, you can be confident that wrapper-related execution issues have been eliminated.

This verification process also helps identify future policy problems before they affect compliance reporting across production environments.

Security Considerations When Using Shell Wrappers

Although shell wrappers solve many command execution problems, they should be used thoughtfully.

Every additional layer of shell processing increases complexity and introduces opportunities for errors if commands are poorly designed.

Following secure scripting practices helps ensure that SCA policies remain both reliable and safe.

Avoid Unnecessary Shell Complexity

Whenever possible, keep command rules simple.

Many compliance checks can be performed using a single executable without relying on shell operators.

For example, this is preferable:

c:systemctl is-enabled sshd

over constructing a lengthy shell pipeline when a simple command is sufficient.

Keeping Checks Maintainable

Simple commands provide several advantages:

Easier troubleshooting
Improved readability
Better portability
Lower maintenance overhead
Reduced likelihood of unexpected behavior

Security engineers from organizations such as the Center for Internet Security (CIS) consistently emphasize simplicity and repeatability when implementing automated compliance validation because overly complex checks are more difficult to audit and maintain.

Reducing Execution Risk

Avoid:

Deeply nested command substitutions
Long pipelines
Multiple chained conditionals
Excessive shell scripting inside policy definitions

If a command becomes difficult to understand at a glance, consider simplifying it before deploying it.

Validate User-Supplied Data

If custom SCA policies incorporate variables or externally generated values, validate those inputs carefully.

Preventing Command Injection Risks

Never allow untrusted input to become part of a shell command without proper validation.

Unsafe example:

/bin/sh -c "grep $USER_INPUT /etc/passwd"

If $USER_INPUT contains unexpected shell characters, the command may behave unpredictably.

Although most SCA policies use static commands, organizations generating policies programmatically should pay particular attention to input validation.

The OWASP Command Injection Prevention Cheat Sheet recommends avoiding shell invocation whenever possible and properly validating or escaping any dynamic input before execution.

Safe Command Construction

Prefer:

Static command strings
Explicit file paths
Known command arguments
Minimal use of variables

This approach reduces both security risk and troubleshooting complexity.

Limit Privilege Requirements

SCA assessments should execute with only the permissions necessary to evaluate compliance.

Running Checks with Minimum Permissions

Avoid designing policies that require elevated privileges unless absolutely necessary.

Whenever possible:

Read configuration files instead of modifying them.
Query services instead of restarting them.
Collect information without making system changes.

This aligns with the Principle of Least Privilege, one of the most widely accepted security design principles.

Avoiding Unnecessary Escalation

Avoid:

Running privileged shell scripts
Invoking sudo within SCA commands
Executing administrative utilities unnecessarily

Keeping command execution read-only minimizes operational risk.

Document Wrapper Usage

As environments grow, undocumented policy changes become increasingly difficult to troubleshoot.

Improving Future Troubleshooting

Whenever a shell wrapper is introduced, document:

Why it was required
Which shell features are being used
Any distribution-specific assumptions
Testing procedures
Expected output

Future administrators will be able to understand the rationale without reverse engineering complex command syntax.

Maintaining Policy Clarity

Good documentation should accompany every custom SCA policy.

Consider maintaining:

Change history
Policy version numbers
Test results
Reviewer notes
Compatibility information

Well-documented policies reduce maintenance costs and make future upgrades significantly easier.

For additional guidance on managing custom configurations, see:

How to Create Custom Detection Rules in Wazuh (With Examples)

Best Practices for Reliable SCA Command Checks

Reliable Security Configuration Assessment policies are built on consistency, simplicity, and regular maintenance.

The following best practices help minimize execution failures while improving the long-term accuracy of compliance reporting.

Prefer Simple Commands Whenever Possible

Use direct commands whenever they can accomplish the required validation.

Avoid introducing shell wrappers solely for convenience if a standalone command produces the same result.

Simpler commands:

Execute more predictably
Require less troubleshooting
Improve policy readability
Reduce platform-specific behavior

Standardize on a Shell Wrapper Strategy

If your organization regularly develops custom SCA policies, establish a consistent approach to shell wrappers.

For example:

Use /bin/sh -c for portable POSIX-compatible commands.
Reserve /bin/bash -c for Bash-specific functionality only.
Document exceptions within the policy.

A standardized approach makes policies easier to review and reduces inconsistencies across teams.

Test Policies Across Different Linux Distributions

Different Linux distributions may use different default shells, package versions, command locations, and service managers.

Before deploying a custom policy broadly, validate it on each supported operating system, such as:

Ubuntu
Debian
Rocky Linux
AlmaLinux
RHEL
SUSE Linux

Cross-platform testing helps identify compatibility issues before they affect production systems.

Verify Expected Output Formats

Many SCA checks compare exact command output.

Even minor formatting differences can produce unexpected failures.

When validating commands, verify:

Whitespace
Capitalization
Line endings
Exit codes
Command output format

Testing against representative production systems helps prevent false negatives caused by formatting variations.

Review Custom Policies After Wazuh Upgrades

Wazuh upgrades may introduce changes to:

SCA policy syntax
Supported features
Execution behavior
Default benchmark content

After upgrading your environment, review custom policies to ensure they continue functioning correctly.

Run sample assessments and compare results against previous compliance reports to identify any regressions early.

For upgrade-related guidance, see:

How to Upgrade a Wazuh Agent

Maintain Version Control for SCA Policies

Treat SCA policies like application source code.

Store them in a version control system such as Git so you can:

Track changes
Review modifications
Roll back problematic updates
Collaborate safely
Maintain an audit trail

Version control significantly simplifies troubleshooting when a policy begins producing unexpected results after a modification.

Periodically Audit Compliance Checks

Even stable policies should be reviewed periodically.

Infrastructure changes, operating system updates, and application upgrades can all affect command behavior over time.

Schedule regular reviews to:

Validate command output
Remove obsolete controls
Update deprecated commands
Confirm benchmark relevance
Identify new optimization opportunities

Routine audits ensure that your Security Configuration Assessment policies continue providing accurate, trustworthy compliance data long after they are first deployed.

For ongoing maintenance guidance, you may also find these resources helpful:

Troubleshooting Checklist

If adding a shell wrapper doesn’t immediately resolve your SCA command failures, work through the following checklist.

In most cases, one of these verification steps will identify the underlying problem.

Confirm the Command Works Manually

Always begin by running the exact command outside of Wazuh.

Verify that:

The command executes successfully.
It returns the expected output.
The exit code indicates success.
The output matches what the SCA policy expects.

If the command fails in a normal terminal session, the issue is unrelated to Wazuh and should be resolved first.

Verify the Correct Shell Path Exists

Ensure that the shell specified in your wrapper actually exists on the target system.

For example:

ls -l /bin/sh

ls -l /bin/bash

Some minimal Linux distributions or container images may not include Bash by default. If /bin/bash is unavailable, switch to /bin/sh where appropriate.

You can also verify the available shell using:

which sh

and

which bash

Check for Syntax Errors in the Wrapper

Small quoting mistakes are one of the most common causes of failed command execution.

For example, ensure the wrapper follows the proper format:

c:/bin/sh -c "grep PermitRootLogin /etc/ssh/sshd_config | grep no"

Common mistakes include:

Missing quotation marks
Unmatched quotes
Incorrect escaping
Extra shell operators
Typographical errors

If the wrapped command cannot be copied directly into a terminal and executed successfully, review the syntax before deploying it.

Review Wazuh Agent Logs

Next, inspect the agent logs for execution errors.

The primary log file is:

/var/ossec/logs/ossec.log

Helpful searches include:

grep -i sca /var/ossec/logs/ossec.log

and

grep -i error /var/ossec/logs/ossec.log

Look for:

Command execution failures
Permission denied messages
Invalid executable paths
Parsing errors
Timeout messages

For additional logging guidance, see:

Wazuh Logcollector Dropped Messages

Validate Policy File Syntax

Even correctly written commands will fail if the SCA policy itself contains syntax errors.

Review the policy carefully for:

YAML formatting issues
Incorrect indentation
Missing fields
Invalid rule definitions
Improper quotation

Whenever possible, validate the policy on a non-production system before deployment.

Test with Simplified Commands

If a complex command continues to fail, simplify it until the problem becomes apparent.

Instead of:

/bin/sh -c "ps aux | grep sshd | awk '{print $2}'"

start with:

ps aux

Then gradually add:

Pipe processing
Filtering
Variable expansion
Command substitution

This incremental approach quickly isolates the feature causing the failure.

Confirm Required Permissions

Some commands require elevated privileges or access to protected files.

Verify that the Wazuh agent has sufficient permissions to:

Read configuration files
Execute required binaries
Access system directories
Query services

Permission-related failures often resemble wrapper issues, so they should always be ruled out.

Rerun the SCA Scan and Review Results

After making corrections:

Reload or restart the Wazuh agent.
Trigger a fresh SCA scan.
Review the updated compliance report.
Compare results with manual testing.

Successful troubleshooting should produce:

Passed compliance controls
No command execution errors
Accurate benchmark scores
Consistent command output

If problems persist, revisit each troubleshooting step before assuming a more complex issue exists.

For broader diagnostics, you may also find these guides helpful:

Frequently Asked Questions (FAQ)

Question: Why do Wazuh SCA command rules fail without a shell wrapper?

Wazuh executes SCA command rules directly rather than through an interactive shell.

As a result, shell-specific features such as pipes (|), command chaining (&&), variable expansion ($HOME), command substitution ($(...)), and output redirection (>) are not interpreted unless the command is explicitly executed through a shell wrapper like /bin/sh -c or /bin/bash -c.

Question: What shell wrapper should I use: `/bin/sh -c` or `/bin/bash -c`?

In most cases, /bin/sh -c is the preferred option because it offers the best compatibility across Linux distributions and supports standard POSIX shell features.

Use /bin/bash -c only when your command relies on Bash-specific functionality such as arrays, process substitution, extended pattern matching, or other Bash-exclusive features.

Question: Do all SCA command rules require a shell wrapper?

No.

Simple commands that execute a single program without shell operators generally work without a wrapper.

For example:

c:hostname

c:uname -r

Shell wrappers are typically only necessary when the command depends on shell processing.

Question: How can I tell if a command depends on shell features?

A command likely requires a shell wrapper if it contains any of the following:

Pipes (|)
Redirect operators (>, >>, <)
Logical operators (&&, ||)
Environment variables ($PATH, $HOME)
Command substitution ($(...))
Wildcards (*)
Loops or conditional statements

If you’re unsure, try running the command using /bin/sh -c in a terminal and compare the output with the unwrapped version.

Question: Can shell wrappers impact SCA scan performance?

For most environments, the performance impact is negligible.

Launching a shell introduces a small amount of additional overhead, but SCA scans typically execute relatively few commands compared to other Wazuh components such as log collection or File Integrity Monitoring.

The accuracy gained by properly executing complex commands usually outweighs the minimal performance cost.

Question: Are shell wrappers supported on all Linux distributions?

Nearly all Linux distributions provide a POSIX-compliant shell at /bin/sh.

Bash is also widely available but may be absent from lightweight distributions, minimal container images, or embedded systems.

Before using /bin/bash -c, verify that Bash is installed on every system targeted by the SCA policy.

Question: Can missing shell wrappers cause false compliance failures?

Yes.

This is one of the most common consequences of wrapper-related issues.

If a command fails to execute correctly, Wazuh may incorrectly mark a compliant system as non-compliant because the expected output is never produced.

These false negatives can reduce compliance scores and trigger unnecessary remediation work.

Question: How do I test an SCA command before deploying it?

The safest approach is to:

Execute the command manually.
Run it again using the intended shell wrapper.
Confirm that the output matches the SCA policy expectations.
Deploy the updated policy to a test system.
Trigger a new SCA scan.
Verify the resulting compliance status before rolling the policy out to production.

This process significantly reduces the likelihood of introducing inaccurate compliance findings across your environment.

Conclusion

Security Configuration Assessment is one of Wazuh’s most effective features for continuously validating system hardening and compliance, but its command-based checks can produce misleading results if administrators overlook how the SCA engine executes commands.

Because Wazuh does not automatically invoke a shell when running SCA command rules, features such as pipes, command chaining, variable expansion, output redirection, and command substitution may fail unexpectedly.

In many cases, simply wrapping the command with /bin/sh -c or /bin/bash -c resolves these issues and restores accurate control evaluation.

Throughout this guide, we’ve covered the most common failure scenarios, including pipeline processing, environment variable expansion, command substitution, and complex shell constructs.

We also explored practical techniques for identifying affected policies, applying shell wrappers correctly, validating the fix, and troubleshooting remaining execution problems.

Equally important is verifying that commands behave the same way inside the SCA execution environment as they do during manual testing.

Reviewing agent logs, confirming policy syntax, and comparing automated results with terminal output can help eliminate false negatives and improve confidence in your compliance reports.

To keep your Security Configuration Assessment policies reliable over time:

Favor simple, maintainable commands whenever possible.
Use shell wrappers only when shell functionality is required.
Test policies across all supported operating systems.
Review custom policies after Wazuh upgrades.
Store SCA policies in version control.
Periodically audit compliance checks to ensure they remain accurate.

By understanding how the SCA engine executes command rules and following these best practices, you can build robust compliance policies that produce consistent, trustworthy results while reducing unnecessary troubleshooting during audits and security assessments.

For additional Wazuh troubleshooting and hardening guidance, you may also find these articles useful: