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:
- Notify the user immediately
- Provide the specific reason for the flag (e.g., signature match vs. binary data)
- 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: https://github.com/openclaw/skills/tree/main/skills/matrix-meta/hex-vetter/SKILL.md
The post Understanding hex-vetter: Physical-Layer Hex Auditing for Skill Security first appeared on Insight Ginie.
