openscan

# OpenScan

Lightweight malware detection for macOS and Linux binaries/scripts. Ported from the Harkonnen antimalware engine.

## What It Detects

**Binary Analysis:**
- Mach-O (macOS) and ELF (Linux) parsing
- Suspicious dylibs/shared objects (Frida, injection frameworks)
- Missing/invalid code signatures (macOS)
- Disabled security features (PIE, NX, RELRO)
- Packed/encrypted binaries (high entropy)

**Pattern Detection:**
- Shellcode byte sequences
- Suspicious API references (process injection, keylogging, etc.)
- Network indicators (embedded URLs, IPs)
- Encoded payloads (base64 blobs)

**Script Analysis:**
- Dangerous shell patterns (curl|bash, eval, etc.)
- Obfuscation indicators
- Privilege escalation attempts

## Usage

```bash
# Scan a single binary
node bin/scan.js /path/to/binary

# Scan a skill folder
node bin/scan.js /path/to/skill-folder

# JSON output for automation
node bin/scan.js /path --json

# Only show threats
node bin/scan.js /path --quiet
```

## Exit Codes

- `0` - Clean (score ≤ 20)
- `1` - Suspicious (score 21-60)
- `2` - High threat (score > 60)

## Threat Scoring

Each file receives a score from 0-100:

| Score | Level    | Meaning                              |
|-------|----------|--------------------------------------|
| 0-20  | CLEAN    | No significant findings              |
| 21-40 | LOW      | Minor concerns, probably safe        |
| 41-60 | MEDIUM   | Suspicious patterns, review manually |
| 61-80 | HIGH     | Likely malicious or dangerous        |
| 81-100| CRITICAL | Known malicious patterns             |

## Integration with OpenClaw

Use before installing or trusting unknown binaries:

```javascript
// Example: scan before allowing a skill's binary
const { scanFile } = require('openscan/lib/scanner');

async function checkBinary(binPath) {
  const result = await scanFile(binPath);
  if (result.threatScore > 40) {
    throw new Error(`Binary failed security scan: ${result.findings.join(', ')}`);
  }
  return true;
}
```

## Li...

# OpenScan

A lightweight malware detection library for OpenClaw, targeting macOS and Linux binaries and scripts. Ported from the [Harkonnen](https://github.com/dev-null321/Harkonnen) antimalware engine.

## Why This Exists

OpenClaw skills can declare binary dependencies via `requires.bins`. Users install these binaries from various sources (Homebrew, npm, apt, random GitHub releases). There's currently no verification that these binaries are safe.

This scanner provides:
- **Pre-trust scanning** of binaries before execution
- **Skill folder auditing** to catch malicious scripts
- **Programmatic API** for integration into OpenClaw's skill loading

## Features

### Binary Analysis

| Platform | Format | Detection |
|----------|--------|-----------|
| macOS | Mach-O (32/64-bit, Universal/FAT) | Suspicious dylibs, code signature, encryption, security flags |
| Linux | ELF (32/64-bit) | Suspicious shared objects, security features (PIE, NX, RELRO) |

**What it checks:**
- **Suspicious libraries**: Frida, Cynject, MobileSubstrate, injection frameworks
- **Code signatures**: Missing or invalid signatures (macOS)
- **Security features**: ASLR/PIE disabled, executable stack/heap, missing NX
- **Packing/encryption**: High entropy detection, encrypted segments
- **Segment anomalies**: Suspicious names like `__INJECT`, `UPX`, `__MALWARE`

### Pattern Detection

Scans binary content for:
- **Shellcode patterns**: x86/x64 prologue sequences, NOP sleds, infinite loops
- **Suspicious APIs**: Process injection (CreateRemoteThread, VirtualAllocEx), keylogging (GetAsyncKeyState), anti-debugging (IsDebuggerPresent)
- **Network indicators**: Embedded URLs, IP addresses
- **Encoded payloads**: Large base64 blobs

### Script Analysis

For shell scripts, Python, JavaScript, etc.:
- **Dangerous patterns**: `curl | bash`, `eval()`, base64 decode + exec
- **Persistence mechanisms**: crontab, launchctl, LaunchAgents
- **Injection vectors**: `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`
- **Obfuscati...