unk-scanner 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 UNK_DeadDrop research contributors
+
+This license applies only to original code, tests, configuration and detection
+rules in this companion repository. It does not cover research prose or any
+third-party evidence.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# unk-scanner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local, static JavaScript triage based on the [UNK_DeadDrop investigation](https://krasforge.github.io/UNK_DeadDrop/). Acorn parses the input without executing it. The scanner reports literal and allowlisted identifier campaign markers, syntactic clipboard writes, and a specific encrypted-loader pattern with one-based source locations.
+
+## Install and run
+
+Requires Node.js 22 or later. Version 0.1.0 is prepared for release; npm publication is pending. Install the locally built tarball:
+
+```sh
+npm install --global ./unk-scanner-0.1.0.tgz --ignore-scripts
+unk-scanner suspect.js > findings.json
+unk-scanner --help
+unk-scanner --version
+```
+
+Use `unk-scanner -- ./-filename.js` for option-like paths. The command accepts one UTF-8 JavaScript file, up to 8 MiB, and emits JSON. For gzip-compressed HTTP bodies, use `unk-scanner --gzip input.js`. Both compressed and decoded sizes are capped at 8 MiB. Without the flag, gzip magic produces an actionable error. Exit status 0 means analysis completed, including when findings exist. Status 2 means invalid arguments, unreadable input, encoding failure, or parse failure. Errors go to stderr.
+
+## Findings and limits
+
+With `--gzip`, top-level hashes and sizes describe the original compressed input; `decoded` records the decoded SHA-256, byte count, and encoding. Locations refer to decoded JavaScript.
+
+The JSON includes schemaVersion, the original file's SHA-256, byte count, findings, and limitations. Each finding contains kind, line, column, and detail. Clipboard literal details are truncated to 240 JavaScript string code units; dynamic arguments are marked unresolved.
+
+The scanner folds string literals, templates without interpolation, and literal concatenation. It supports module syntax with a script-syntax fallback. It does not resolve aliases, track data flow or reachability, decrypt payloads, or decode obfuscated string tables. A marker or clipboard write alone does not establish maliciousness; an empty result does not establish safety.
+
+Analysis does not execute or import the input, install its dependencies, or contact remote infrastructure. Output can contain source strings. Handle reports with the input's sensitivity. The CLI parses in a worker with a 10-second deadline and V8 heap limits (256 MiB old generation, 32 MiB young generation). A maximum of 10,000 findings prevents unbounded reports. Limit failures return exit 2 without a partial report. These are application limits, not a security sandbox or a total process-memory guarantee. Use operating-system isolation for untrusted inputs.
+
+## Encrypted-loader findings
+
+An `encrypted-loader` finding links a specific top-level sequence: a literal base64 buffer, its IV/tag/ciphertext slices, an AES-256-GCM decipher, authentication-tag assignment, conversion of update/final output to text, and an `_compile` call receiving that text. Evidence locations identify five steps without copying keys or encrypted payloads into the report.
+
+Recognition follows direct top-level `const` bindings. It tolerates renamed variables and literal-computed method names. It does not evaluate expressions, decrypt anything, establish that receivers are genuine Node APIs, or prove execution or successful authentication. Other loader layouts, nested scopes, mutable bindings, and string-table obfuscation may remain unmatched. Encryption or compilation alone does not trigger this finding; it is not campaign attribution.
+
+## Exact artifact identity
+
+`artifactMatches` is separate from `findings`. It identifies three exact decoded-source hashes retained in the investigation: the login interface, a shared module-preload polyfill, and the obfuscated extension entry point. The login interface has classification `context-only`; the polyfill is a `shared-web-component`. Neither is a malware alert or an attribution indicator. The extension match identifies the retained bytes but does not resolve its behavior.
+
+With gzip input, identity matches use the decoded source hash, while the top-level hash still describes the original input. Any source-byte change invalidates exact identity. Do not merge identity counts into behavioral detection or recall statistics. Review context at the [research series](https://krasforge.github.io/UNK_DeadDrop/).
+
+## JavaScript API
+
+```js
+import { inspect } from 'unk-scanner';
+const result = inspect('navigator.clipboard.writeText("example");');
+```
+
+The synchronous API runs in the caller process without the CLI worker deadline or heap limits. The API accepts source text and hashes its UTF-8 encoding. The CLI hashes original file bytes, including any UTF-8 byte-order mark.
+
+## Development
+
+From the companion repository root:
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm pack --workspace unk-scanner
+```
+
+Code is MIT licensed. Acorn retains its own license. This package includes no malware samples, YARA rules, or credentials. Existing YARA validation statistics do not measure scanner accuracy.

package/bin/unk-scanner.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+main(process.argv.slice(2)).catch(error => {
+  process.stderr.write('unk-scanner: ' + error.message + '\n');
+  process.exitCode = 2;
+});

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "unk-scanner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Static JavaScript triage for UNK_DeadDrop campaign markers and clipboard writes",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "unk-scanner": "bin/unk-scanner.mjs"
+  },
+  "exports": "./src/inspect.mjs",
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "acorn": "8.17.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KrasForge/unk-deaddrop-companion.git",
+    "directory": "packages/unk-scanner"
+  },
+  "homepage": "https://krasforge.github.io/UNK_DeadDrop/",
+  "keywords": [
+    "security",
+    "static-analysis",
+    "javascript",
+    "acorn",
+    "unk-deaddrop"
+  ]
+}

package/src/artifacts.mjs

@@ -0,0 +1,24 @@
+// Exact decoded-source identities. These describe retained evidence, not
+// generalized malware signatures. Shared web components must not be alerts.
+const artifacts = new Map([
+  ['5557912dedf7f75666683afbe2632e0b89b8ee23f621432296a9c48eff63e9f4', {
+    name: 'Retained Domatisc login interface',
+    classification: 'context-only',
+    explanation: 'Login and animation code retained from the observed panel. Its content alone does not establish malicious behavior.',
+  }],
+  ['785597bca2e7dd97a652a20a197c077079e635a5663433448e0e1d9fd8c98a64', {
+    name: 'Retained module-preload polyfill',
+    classification: 'shared-web-component',
+    explanation: 'Generic module-preload compatibility code. An identical copy elsewhere does not establish a campaign association.',
+  }],
+  ['d5e9288693aa745dc89368deac677e7ea1ec81e663283af30838cdae189b7a7e', {
+    name: 'Retained google-dev-tools extension entry point',
+    classification: 'known-investigation-artifact',
+    explanation: 'Exact retained obfuscated extension source. This match identifies these bytes; the scanner has not resolved its runtime behavior.',
+  }],
+]);
+
+export function identifyArtifact(sha256) {
+  const artifact = artifacts.get(sha256);
+  return artifact ? [{ ...artifact, match: 'exact-source-sha256', sha256 }] : [];
+}

package/src/bounded.mjs

@@ -0,0 +1,33 @@
+import { Worker } from 'node:worker_threads';
+
+// A worker bounds CLI parser runtime and V8 heap use. It never imports the input.
+export function inspectBounded(source, { timeoutMs = 10000 } = {}) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60000) {
+    return Promise.reject(new Error('Timeout must be an integer from 1 to 60000 ms'));
+  }
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL('./worker.mjs', import.meta.url), {
+      workerData: source,
+      resourceLimits: { maxOldGenerationSizeMb: 256, maxYoungGenerationSizeMb: 32, stackSizeMb: 4 },
+      execArgv: [],
+    });
+    let finished = false;
+    const finish = (error, result) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      if (error) reject(error);
+      else resolve(result);
+    };
+    const timer = setTimeout(() => finish(new Error('Analysis timed out; no complete result')), timeoutMs);
+    worker.once('message', message => {
+      if (message.error) finish(new Error(message.error));
+      else finish(null, message.result);
+    });
+    worker.once('error', error => finish(new Error('Analysis worker failed: ' + error.message)));
+    worker.once('exit', code => {
+      if (!finished) finish(new Error('Analysis worker exited without a result (code ' + code + ')'));
+    });
+  });
+}

package/src/cli.mjs

@@ -0,0 +1,57 @@
+import { open, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { MAX_BYTES } from './inspect.mjs';
+import { inspectBounded } from './bounded.mjs';
+import { gunzipSync } from 'node:zlib';
+const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+export async function main(args) {
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    process.stdout.write('Usage: unk-scanner [--gzip] [--] FILE.js\n       unk-scanner --help | --version\n\nStatic JavaScript triage; emits JSON. Findings are review leads.\nExit 0: analysis completed (with or without findings). Exit 2: error.\n');
+    return;
+  }
+  if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+    process.stdout.write(version + '\n');
+    return;
+  }
+  const gzip = args[0] === '--gzip';
+  if (gzip) args = args.slice(1);
+  if (args[0] === '--') args = args.slice(1);
+  else if (args[0]?.startsWith('-')) throw new Error('Unknown option: ' + args[0]);
+  if (args.length !== 1) throw new Error('Usage: unk-scanner [--gzip] [--] FILE.js');
+  const handle = await open(args[0], constants.O_RDONLY | constants.O_NONBLOCK);
+  let bytes;
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error('Input must be a regular file');
+    if (stat.size > MAX_BYTES) throw new Error('Input exceeds 8 MiB limit');
+    // Read at most the limit plus one, including if the input grows after stat().
+    const buffer = Buffer.alloc(MAX_BYTES + 1);
+    let count = 0;
+    while (count < buffer.length) {
+      const read = await handle.read(buffer, count, buffer.length - count, null);
+      if (!read.bytesRead) break;
+      count += read.bytesRead;
+    }
+    if (count > MAX_BYTES) throw new Error('Input exceeds 8 MiB limit');
+    bytes = buffer.subarray(0, count);
+  } finally {
+    await handle.close();
+  }
+  if (!gzip && bytes[0] === 0x1f && bytes[1] === 0x8b) {
+    throw new Error('Gzip input detected; use --gzip to decode with an 8 MiB output limit');
+  }
+  const decoded = gzip ? gunzipSync(bytes, { maxOutputLength: MAX_BYTES }) : bytes;
+  const source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(decoded);
+  const result = await inspectBounded(source);
+  if (gzip) {
+    result.decoded = {
+      encoding: 'gzip', bytes: decoded.length,
+      sha256: createHash('sha256').update(decoded).digest('hex'),
+    };
+  }
+  result.sha256 = createHash('sha256').update(bytes).digest('hex');
+  result.bytes = bytes.length;
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/src/inspect.mjs

@@ -0,0 +1,101 @@
+import { identifyArtifact } from './artifacts.mjs';
+import { encryptedLoaders } from './loaders.mjs';
+import { parse } from 'acorn';
+import { createHash } from 'node:crypto';
+
+export const MAX_FINDINGS = 10000;
+export const MAX_BYTES = 8 * 1024 * 1024;
+const MARKERS = /OVERLORD_COMPANY_WALLET_EP|OVERLORD_SERVER_RAW|OVERLORD_KEEP_AGENT_STATE|X-Company-Wallet-Client-Id|\/api\/company-wallet\/upload|GoogleUpdateSupporterNode|GUS_UPLOAD_CHUNK_SIZE|DEFAULT_PHASE3_MAX_MS|DEFAULT_PHASE3_ROOT_MAX_MS|WIN_NODE_AGENT_BUNDLE_B64|DEFAULT_WALK_MAX_DIRS|CREDENTIAL_NAME_RE|macTccReadableCache|CloudStorage|ELECTRON_RUN_AS_NODE|--company-wallet-phase1-local|--company-wallet-job|--win-build-ep-only|cmdline_copied|perl -MPOSIX|POSIX::setsid|curl -ks|start -WindowStyle Hidden cmd|VERIFY-|IElevator|detect_malware\.py|3E5FC7F9-9A51-4367-9063-A120244FBEC7|gus-phase2-|sa-elev-done-|app_bound_encrypted_key/g;
+
+// Only literal syntax is folded. No variable resolution, calls or coercion.
+export function literalString(node, depth = 0) {
+  if (!node || depth > 32) return undefined;
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0].value.cooked ?? undefined;
+  }
+  if (node.type === 'BinaryExpression' && node.operator === '+') {
+    const left = literalString(node.left, depth + 1);
+    const right = literalString(node.right, depth + 1);
+    if (left !== undefined && right !== undefined) return left + right;
+  }
+  return undefined;
+}
+const IDENTIFIER_MARKERS = new Set([
+  'OVERLORD_COMPANY_WALLET_EP', 'OVERLORD_SERVER_RAW', 'OVERLORD_KEEP_AGENT_STATE',
+  'GUS_UPLOAD_CHUNK_SIZE', 'DEFAULT_PHASE3_MAX_MS', 'DEFAULT_PHASE3_ROOT_MAX_MS',
+  'WIN_NODE_AGENT_BUNDLE_B64', 'DEFAULT_WALK_MAX_DIRS', 'CREDENTIAL_NAME_RE',
+  'macTccReadableCache', 'ELECTRON_RUN_AS_NODE', 'app_bound_encrypted_key',
+]);
+
+function memberName(node) {
+  while (node?.type === 'ChainExpression') node = node.expression;
+  if (node?.type !== 'MemberExpression') return undefined;
+  return node.computed ? literalString(node.property) : node.property.name;
+}
+
+export function inspect(source) {
+  if (typeof source !== 'string') throw new TypeError('Expected JavaScript text');
+  if (Buffer.byteLength(source) > MAX_BYTES) throw new Error('Input exceeds 8 MiB limit');
+  let ast;
+  try {
+    ast = parse(source, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    ast = parse(source, { ecmaVersion: 'latest', sourceType: 'script', locations: true });
+  }
+  const findings = [];
+  const seen = new Set();
+  const add = (kind, node, detail, extra = {}) => {
+    const key = `${kind}:${node.start}:${detail}`;
+    if (seen.has(key)) return;
+    if (findings.length >= MAX_FINDINGS) throw new Error('Finding limit exceeded; no complete result');
+    seen.add(key);
+    findings.push({ kind, line: node.loc.start.line, column: node.loc.start.column + 1, detail, ...extra });
+  };
+  const pending = [ast];
+  while (pending.length) {
+    const node = pending.pop();
+    if (node.type === 'Identifier' && IDENTIFIER_MARKERS.has(node.name)) {
+      add('campaign-marker', node, node.name);
+    }
+    const value = literalString(node);
+    if (value !== undefined) {
+      for (const match of value.matchAll(MARKERS)) add('campaign-marker', node, match[0]);
+    }
+    if (node.type === 'CallExpression') {
+      const callee = node.callee.type === 'ChainExpression' ? node.callee.expression : node.callee;
+      const method = memberName(callee);
+      const owner = memberName(callee?.object);
+      if ((method === 'writeText' && owner === 'clipboard') ||
+          (method === 'setData' && owner === 'clipboardData')) {
+        const arg = node.arguments[method === 'setData' ? 1 : 0];
+        const text = literalString(arg);
+        add('clipboard-write', node, text === undefined ? 'dynamic argument; unresolved' : text.slice(0, 240));
+      }
+    }
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const child of value) if (child?.type) pending.push(child);
+      } else if (value?.type) pending.push(value);
+    }
+  }
+  for (const loader of encryptedLoaders(ast, literalString)) {
+    add('encrypted-loader', loader.node,
+      'Embedded base64, AES-GCM authentication, and decoded text linked syntactically to _compile',
+      { evidence: loader.evidence });
+  }
+  findings.sort((a, b) => a.line - b.line || a.column - b.column || a.kind.localeCompare(b.kind));
+  const sha256 = createHash('sha256').update(source).digest('hex');
+  return {
+    schemaVersion: 1,
+    sha256,
+    artifactMatches: identifyArtifact(sha256),
+    bytes: Buffer.byteLength(source),
+    findings,
+    limitations: ['Syntactic matches only; no data-flow or reachability proof',
+      'No general alias resolution or encoded string-table deobfuscation',
+      'Encrypted-loader recognition covers only a specific top-level const-binding pattern',
+      'A clipboard write or marker alone is not a maliciousness verdict'],
+  };
+}

package/src/loaders.mjs

@@ -0,0 +1,68 @@
+// Recognize a narrow top-level const-binding pattern. Names may vary; input is
+// never evaluated. This establishes syntax relationships, not runtime behavior.
+export function encryptedLoaders(ast, literalString) {
+  const bindings = new Map();
+  const calls = [];
+  const method = node => node?.type === 'MemberExpression'
+    ? (node.computed ? literalString(node.property) : node.property.name) : undefined;
+  const id = node => node?.type === 'Identifier' ? node.name : undefined;
+  const isCall = (node, name) => node?.type === 'CallExpression' && method(node.callee) === name;
+  const binding = (node, before) => {
+    const found = bindings.get(id(node));
+    return found && found.start < before ? found.init : undefined;
+  };
+  const collect = expression => {
+    if (expression?.type === 'SequenceExpression') expression.expressions.forEach(collect);
+    else if (expression?.type === 'CallExpression') calls.push(expression);
+  };
+  for (const statement of ast.body) {
+    if (statement.type === 'VariableDeclaration' && statement.kind === 'const') {
+      for (const declaration of statement.declarations) {
+        if (declaration.id.type === 'Identifier') bindings.set(declaration.id.name, declaration);
+      }
+    } else if (statement.type === 'ExpressionStatement') collect(statement.expression);
+  }
+  const slice = (node, before, start, end) => {
+    const init = binding(node, before);
+    if (!isCall(init, 'subarray')) return undefined;
+    const args = init.arguments;
+    if (args.length !== (end === undefined ? 1 : 2) ||
+        args[0]?.type !== 'Literal' || args[0].value !== start ||
+        (end !== undefined && (args[1]?.type !== 'Literal' || args[1].value !== end))) return undefined;
+    return id(init.callee.object);
+  };
+  const results = [];
+  for (const compile of calls) {
+    if (!isCall(compile, '_compile')) continue;
+    const source = binding(compile.arguments[0], compile.start);
+    if (!isCall(source, 'toString') || !['utf8', 'utf-8'].includes(literalString(source.arguments[0]))) continue;
+    const concat = source.callee.object;
+    if (!isCall(concat, 'concat') || id(concat.callee.object) !== 'Buffer' ||
+        concat.arguments.length !== 1 || concat.arguments[0].type !== 'ArrayExpression') continue;
+    const parts = concat.arguments[0].elements;
+    if (parts.length !== 2 || !isCall(parts[0], 'update') || !isCall(parts[1], 'final')) continue;
+    const decipherName = id(parts[0].callee.object);
+    if (!decipherName || id(parts[1].callee.object) !== decipherName) continue;
+    const decipher = binding(parts[0].callee.object, source.start);
+    if (!isCall(decipher, 'createDecipheriv') || literalString(decipher.arguments[0]) !== 'aes-256-gcm') continue;
+    const payloadName = slice(decipher.arguments[2], decipher.start, 0, 12);
+    if (!payloadName || slice(parts[0].arguments[0], source.start, 28) !== payloadName) continue;
+    const payload = bindings.get(payloadName);
+    if (!payload || payload.start >= decipher.start || !isCall(payload.init, 'from') ||
+        id(payload.init.callee.object) !== 'Buffer' ||
+        literalString(payload.init.arguments[1]) !== 'base64' ||
+        literalString(payload.init.arguments[0]) === undefined) continue;
+    const tag = calls.find(call => isCall(call, 'setAuthTag') &&
+      id(call.callee.object) === decipherName && call.start > decipher.start && call.start < source.start &&
+      slice(call.arguments[0], call.start, 12, 28) === payloadName);
+    if (!tag) continue;
+    results.push({
+      node: compile,
+      evidence: [
+        ['embedded-base64', payload.init], ['aes-256-gcm', decipher],
+        ['authentication-tag', tag], ['decoded-text', source], ['module-compile', compile],
+      ].map(([role, node]) => ({ role, line: node.loc.start.line, column: node.loc.start.column + 1 })),
+    });
+  }
+  return results;
+}

package/src/worker.mjs

@@ -0,0 +1,8 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { inspect } from './inspect.mjs';
+
+try {
+  parentPort.postMessage({ result: inspect(workerData) });
+} catch (error) {
+  parentPort.postMessage({ error: error.message });
+}