Understanding hex-vetter: Physical-Layer Hex Auditing for Skill Security

What is hex-vetter?

hex-vetter is a physical-layer hex auditing skill that performs deep hex-level
analysis of files to detect what text-based reviewers miss. It's designed
specifically for security audits of skill packages, detecting hidden payloads,
obfuscated code, and suspicious binary data that could pose security risks.

Why Physical-Layer Analysis Matters

Traditional text-based code review methods can miss critical security issues
because they only examine the surface level of files. Malicious actors often
hide dangerous content using various techniques:

• Binary injection through null bytes
• Control characters that manipulate terminal behavior
• Unicode directional overrides that hide text
• Base64 or other encoded payloads
• Known malware signatures

hex-vetter addresses these blind spots by examining files at the hex level,
where the actual binary data lives regardless of how it's presented in text
editors or IDEs.

Core Features and Detection Capabilities

The skill detects multiple categories of suspicious content:

Binary Injection Detection

Null bytes (0x00) are a common sign of binary injection or file padding. These
can be used to trick parsers or hide malicious content between legitimate
text. hex-vetter flags any occurrence of null bytes as a potential security
concern.

Control Character Analysis

Control characters (0x01-0x1F) can create hidden terminal sequences that
manipulate how text is displayed or processed. These characters might be used
to hide malicious commands or create confusing visual presentations that
deceive users.

Unicode Manipulation Detection

Unicode directional overrides like LRO (Left-to-Right Override) and RLO
(Right-to-Left Override) can be used to reverse text direction, potentially
hiding malicious content or creating confusing command sequences.

Encoding Analysis

A high ratio of non-ASCII bytes often indicates Base64 encoding or other
encoding schemes that might be hiding malicious payloads. hex-vetter analyzes
the distribution of byte values to detect suspicious encoding patterns.

Signature Matching

The skill includes a database of known magic bytes and signatures that can
identify specific file types or known malicious patterns. This helps detect
malware, compressed archives, or other suspicious file formats.

Installation and Usage

Command Line Interface

hex-vetter provides a simple command-line interface for scanning files and
directories:

git clone https://github.com/Matrix-Meta/hex-vetter.git
cd hex-vetter
npm install

Basic usage includes:

# Scan a single file
node vet.js <file_path>

# Scan a directory recursively
node scan_all.js <directory_path>

# Verify file integrity
node verify.js <file_path>

Programmatic API

For integration into larger systems, hex-vetter provides a Node.js module
interface:

const { scanFile } = require('./vet.js');
const result = await scanFile('/path/to/file.bin');
console.log(result.riskLevel); // 'LOW', 'MEDIUM', 'HIGH'
console.log(result.flags); // Array of detected issues
console.log(result.hexDump); // Formatted hex output

Understanding Risk Levels

hex-vetter classifies findings into three risk levels:

• 🟢 LOW : Normal file, no suspicious content detected
• 🟡 MEDIUM : Some flags detected, manual review recommended
• 🔴 HIGH : Significant suspicious content, MUST be manually reviewed

The risk assessment is heuristic-based, meaning it uses patterns and
probabilities rather than absolute certainty. This approach helps catch
potential issues while minimizing false positives.

Security Policy and Mandatory Review

hex-vetter enforces a strict security policy: any file flagged as HIGH RISK
must be manually inspected by a human or trusted agent before the skill is
used. This mandatory review process ensures that potentially dangerous content
doesn't slip through automated analysis.

Common False Positives

The system acknowledges that some legitimate files may trigger warnings.
Common false positives include:

• .env mentions in .npmignore files
• Documentation with encoded examples
• Compressed assets and binary files

Agent Action Requirements

When an agent performs an audit and finds HIGH RISK content, it must:

1. Notify the user immediately
2. Provide the specific reason for the flag (e.g., signature match vs. binary data)
3. Suggest next steps for manual review

Technical Architecture

The hex-vetter project is organized into several key components:

• starfragment.js : Core module with self-modifying storage capabilities
• scan_all.js : Recursive directory scanner
• verify.js : Integrity verification module
• vet.js : Main entry point for file scanning

Self-Modifying Storage

One of the most interesting technical features is the use of self-modifying
storage in the starfragment.js module. This module reads and writes data
from/to its own file at runtime, storing constants as valid JavaScript
comments at the end of the source file. This approach allows for persistent
storage without external dependencies while maintaining the file's executable
nature.

API Reference

scanFile() Function

The primary scanning function analyzes a single file and returns comprehensive
results:

const result = await scanFile('./somefile.js');
// Returns: { riskLevel, flags, hexDump, details }

The result object includes the overall risk level, an array of specific flags
detected, a formatted hex dump for manual inspection, and detailed analysis
information.

scanDirectory() Function

For bulk analysis, the scanDirectory function recursively scans all files in a
directory:

const results = await scanDirectory('./skills/');

// Returns: Array of scan results for each file

verifyIntegrity() Function

Integrity verification ensures files haven't been tampered with:

const result = await verifyIntegrity('./starfragment.js');

// Returns: { valid, expected, actual }

Contributing and Development

The hex-vetter project welcomes contributions through GitHub. The modular
architecture makes it easy to extend detection capabilities or improve
existing analysis algorithms. Contributors can add new detection patterns,
improve false positive handling, or enhance the reporting interface.

Real-World Applications

hex-vetter is particularly valuable in several scenarios:

Skill Marketplace Security

For platforms that host and distribute skills or plugins, hex-vetter provides
automated security screening to prevent malicious content from being
distributed to users.

Enterprise Development

Organizations can use hex-vetter to enforce security policies on third-party
code before it's integrated into their systems, reducing the risk of supply
chain attacks.

Educational Environments

In educational settings where students share code, hex-vetter helps ensure
that shared content doesn't contain hidden malicious payloads or inappropriate
content.

Future Enhancements

Potential future developments for hex-vetter include:

• Machine learning-based anomaly detection
• Integration with popular CI/CD pipelines
• Support for additional file formats and encoding schemes
• Real-time scanning for development environments
• Enhanced reporting with actionable remediation steps

Conclusion

hex-vetter represents a crucial advancement in security auditing for skill
packages and similar code distribution systems. By examining files at the
physical layer rather than just the text layer, it catches threats that
traditional code review would miss. The combination of comprehensive detection
capabilities, clear risk assessment, and mandatory review policies makes it an
essential tool for anyone serious about software security.

As the software ecosystem continues to evolve and threats become more
sophisticated, tools like hex-vetter that look beyond surface-level analysis
will become increasingly important for maintaining security and trust in
distributed software systems.

Skill can be found at:
vetter/SKILL.md>