Compare commits

...
Author SHA1 Message Date
morlutoandGitHub 222ce83967 Merge pull request #444 from morluto/release-please--branches--main--components--rea-agents
chore(main): release rea-agents 2.7.0
2026-07-28 15:02:26 +08:00
github-actions[bot] 7929bf1688 chore: normalize release product catalog 2026-07-28 06:54:15 +00:00
github-actions[bot]andGitHub 8ab40974d3 chore(main): release rea-agents 2.7.0 2026-07-28 06:53:17 +00:00
morlutoandGitHub 91fb87d17e Merge pull request #445 from morluto/codex/conformance-package-336
feat(conformance): add portable conformance export package format
2026-07-28 14:52:18 +08:00
morlutoandGitHub 54153ed62c Merge pull request #446 from morluto/codex/protocol-capture-364
feat(protocol): add gRPC/Protobuf and JSON-RPC/MessagePack capture
2026-07-28 14:52:13 +08:00
morlutoandGitHub f942558573 Merge pull request #447 from morluto/codex/pe-coff-inspection-362
feat(pe): add broader PE/COFF/PDB static inspection
2026-07-28 14:52:08 +08:00
morlutoandGitHub 1fb22b4c21 Merge pull request #448 from morluto/codex/custom-protocol-capture-365
feat(protocol): add custom TCP/UDP/IPC/XPC and auth-flow capture
2026-07-28 14:51:58 +08:00
morlutoandGitHub 1a75f8dc23 Merge pull request #449 from morluto/codex/jvm-python-bytecode-367
feat(bytecode): add JVM and Python bytecode providers
2026-07-28 14:51:17 +08:00
morlutoandGitHub 18624df572 Merge pull request #451 from morluto/codex/mobile-providers-366
feat(mobile): add Android APK/AAB/DEX and iOS IPA static investigation providers
2026-07-28 14:51:11 +08:00
morlutoandGitHub 0ef1b91cf3 Merge pull request #450 from morluto/codex/msix-msi-appx-363
feat(package): add MSIX/MSI/AppX package, resource, and signature analysis
2026-07-28 14:51:07 +08:00
morlutoandGitHub 64f64fec30 Merge branch 'main' into codex/pe-coff-inspection-362 2026-07-28 14:26:38 +08:00
morlutoandGitHub 4602efd27c Merge pull request #452 from morluto/codex/objc-swift-metadata-353
feat(metadata): add deeper ObjC/Swift metadata and database save/licensing
2026-07-28 14:26:25 +08:00
morluto 94e6600faf feat(pe): add broader PE/COFF/PDB static inspection
Expand PE/COFF/PDB inspection to cover imports, exports, resources,
manifests, signatures, debug identifiers, sections, relocations, TLS
callbacks, and architecture metadata (#362).

- peInspection.ts: domain schemas for PE manifests with sections,
  imports, exports, resources, debug entries, TLS callbacks, and
  relocations. Parsers for machine types, section characteristics,
  image characteristics, and debug directory types.
- Public contracts do not expose macOS-only vocabulary.
- Unsupported capabilities are reported explicitly.

Closes #362
2026-07-28 14:22:04 +08:00
morlutoandGitHub 4d228b4d8c Merge branch 'main' into codex/objc-swift-metadata-353 2026-07-28 14:21:35 +08:00
morlutoandGitHub a5e355a3d5 Merge pull request #453 from morluto/codex/event-process-tree-332
feat(process): replace procfs sampling with event-backed process-tree capture
2026-07-28 14:21:25 +08:00
morluto fdeeb27f23 feat(mobile): add Android APK/AAB/DEX and iOS IPA static investigation providers
Add static providers for Android APK/AAB/DEX and Apple IPA artifacts,
including manifests, resources, signing, and native libraries (#366).

- mobileApplicationInvestigation.ts: domain schemas for Android
  (APK, AAB, DEX) and iOS (IPA) artifact formats with manifests,
  signing info, resources, and native libraries.
- detectMobileFormat and detectPlatform: classify from extensions
- classifyMobileResource: resource type from path
- Utility functions for native library filtering, internet
  permission checking, and architecture enumeration

Closes #366
2026-07-28 05:54:34 +00:00
morluto d5d2e56d04 feat(process): replace procfs sampling with event-backed process-tree capture
Replace 50 ms procfs sampling with event-backed capture of root/child/
grandchild spawn, exit, re-exec, and reparent events (#332).

- eventProcessTree.ts: domain schemas for event types (spawn, exit,
  re_exec, reparent, signal, name_change, thread_create, thread_exit)
  and reconstructed process nodes with children, timestamps, and
  lineage tracking.
- reconstructProcessTree: rebuilds the full process tree from events,
  tracking short-lived descendants, re-exec, and reparenting.
- Utility functions: getDescendants, containsProcess, maxTreeDepth.
- Integration is cross-platform where supported; unsupported platforms
  report typed unavailability via the event schema.

Closes #332
2026-07-28 05:47:50 +00:00
morluto d7a07535b0 feat(metadata): add deeper ObjC/Swift metadata and database save/licensing
Add deeper Objective-C and Swift metadata extraction, plus database
path/save/licensing behavior where licensing permits (#353).

- objcSwiftMetadata.ts: domain schemas for ObjC classes, protocols,
  methods (instance/class/ivar getter/setter), properties with
  attributes, and Swift declarations (class, struct, enum, protocol,
  extension, actor) with access levels and modifiers.
- Database save/readback operation tracking with preserved names,
  comments, and bookmarks verification.
- Utility functions for selector classification, method counting,
  Swift declaration filtering, and database save completeness.
- Read-only and mutating operations are distinguished.

Closes #353
2026-07-28 05:46:10 +00:00
morluto 6c03f83b1b feat(package): add MSIX/MSI/AppX package, resource, and signature analysis
Add static analysis for MSIX, MSI, AppX packages, their resources,
and digital signatures (#363).

- packageAnalysis.ts: domain schemas for Windows package formats
  (MSIX, MSI, AppX), resources (manifest, icon, configuration,
  certificate, executable, library, data), and digital signatures.
- detectPackageFormat: classifies from file extension
- classifyResource: identifies resource type from path
- Digital signature validation with timestamp detection
- Package and resource contents are inventoried without execution

Closes #363
2026-07-28 05:42:30 +00:00
morluto 4e0127d620 feat(bytecode): add JVM and Python bytecode providers
Add execution-free providers for JVM bytecode/JAR/WAR and Python
bytecode/wheels/zipapps (#367).

- bytecodeProvider.ts: domain schemas for bytecode families (JVM,
  Python), artifact formats (class, jar, war, ear, pyc, pyo, whl,
  zipapp), symbol types, and provenance classification.
- detectBytecodeFamily: classifies artifacts from file extensions
- detectArtifactFormat: identifies artifact format from path
- classifyProvenance: distinguishes application, generated, vendored,
  bundled, and standard_library code
- analyzeBytecodeArtifacts: summarizes total and classified symbols

Closes #367
2026-07-28 05:42:05 +00:00
morluto 6fa6f9b6d9 feat(protocol): add custom TCP/UDP/IPC/XPC and auth-flow capture
Add support for custom TCP and UDP framing, local IPC, Unix sockets,
named pipes, XPC, and authentication/token lifecycle metadata (#365).

- customProtocolCapture.ts: domain schemas for custom protocol
  frames with transport types (TCP, UDP, IPC, Unix socket, named
  pipe, XPC), frame direction, process identity correlation, and
  decoded content.
- Authentication flow events with stage tracking (init, challenge,
  response, token exchange, renewal, revocation, failure, success).
- Token lifecycle events (issued, refreshed, expired, revoked,
  renewed).
- Credential detection and redaction by default.
- Filters for transport type, protocol, and auth success/failure.

Closes #365
2026-07-28 05:41:41 +00:00
morluto 3f336fefb1 feat(protocol): add gRPC/Protobuf and JSON-RPC/MessagePack capture
Add capture and schema inference for gRPC/Protocol Buffers and
JSON-RPC/MessagePack protocols (#364).

- classifyProtocolFamily: detects protocol from content type or path
- decodeJsonRpc: decodes JSON-RPC messages with credential redaction
- decodeMessagePack: decodes MessagePack wire format (map/array detection)
- decodeGrpcFrame: decodes gRPC 5-byte frame headers
- inferMessageSchema: infers schema hypotheses from repeated messages
- Credential-like fields are detected and redacted by default

Closes #364
2026-07-28 05:40:49 +00:00
morluto 4ee30e4145 feat(conformance): add portable conformance export package format
Define a committed scenario/replay/shim/evidence package format for
portable process-fidelity conformance fixtures (#336). The package
format is versioned, path-independent, and consumable from a clean
checkout.

- conformancePackage.ts: top-level package schema with scenario
  manifests, replay plans, shim plans, expected evidence, and
  verifier contracts. Deterministic package ID computed from
  canonical JSON. Cross-reference validation ensures internal
  consistency.
- conformanceTrustGate.ts: trust gates that compare captured runs
  against committed conformance packages (#337). Classifies semantic
  diffs from timing/normalization noise. Unknown/truncated evidence
  is never treated as equivalence.
- conformanceReplay.ts: CI replay engine that runs each scenario,
  evaluates trust gates, and detects drift between captured and
  committed evidence (#338).

Closes #336, #337, #338
2026-07-28 05:40:17 +00:00
morlutoandGitHub 645668b70d Merge pull request #443 from morluto/codex/provider-catalog-digest
fix(catalog): digest provider projections
2026-07-27 00:35:42 +08:00
morlutoandGitHub ba3151891e Merge branch 'main' into codex/provider-catalog-digest 2026-07-27 00:12:31 +08:00
morluto c4cd0330e0 fix(catalog): digest provider projections 2026-07-26 16:07:12 +00:00
37 changed files with 4315 additions and 15 deletions
+1 -1
View File
@@ -1,3 +1,3 @@
{
".": "2.6.0"
".": "2.7.0"
}
+30
View File
@@ -1,5 +1,35 @@
# Changelog
## [2.7.0](https://github.com/morluto/rea/compare/rea-agents-2.6.0...rea-agents-2.7.0) (2026-07-28)
### Features
* **bytecode:** add JVM and Python bytecode providers ([1a75f8d](https://github.com/morluto/rea/commit/1a75f8dc236d8269a5fa07e042471ac79e79d728))
* **bytecode:** add JVM and Python bytecode providers ([4e0127d](https://github.com/morluto/rea/commit/4e0127d620377e5dc7e09444f9db0977e3d47ed1)), closes [#367](https://github.com/morluto/rea/issues/367)
* **conformance:** add portable conformance export package format ([91fb87d](https://github.com/morluto/rea/commit/91fb87d17e7885439762667c96167af79a2e044e))
* **conformance:** add portable conformance export package format ([4ee30e4](https://github.com/morluto/rea/commit/4ee30e4145db9b496158cd980af05e22010856a7))
* **metadata:** add deeper ObjC/Swift metadata and database save/licensing ([4602efd](https://github.com/morluto/rea/commit/4602efd27cbf8701c2dc15542042bc9d9ef76e7f))
* **metadata:** add deeper ObjC/Swift metadata and database save/licensing ([d7a0753](https://github.com/morluto/rea/commit/d7a07535b0fb61ee8f9ae648bb673dda23290653)), closes [#353](https://github.com/morluto/rea/issues/353)
* **mobile:** add Android APK/AAB/DEX and iOS IPA static investigation providers ([18624df](https://github.com/morluto/rea/commit/18624df5724a2c4d14a4e8e178660456424b2344))
* **mobile:** add Android APK/AAB/DEX and iOS IPA static investigation providers ([fdeeb27](https://github.com/morluto/rea/commit/fdeeb27f23041c19b5857fe7873106f0cd9c6244)), closes [#366](https://github.com/morluto/rea/issues/366)
* **package:** add MSIX/MSI/AppX package, resource, and signature analysis ([0ef1b91](https://github.com/morluto/rea/commit/0ef1b91cf31f6ca53991ee5ca60b4a22f430c01e))
* **package:** add MSIX/MSI/AppX package, resource, and signature analysis ([6c03f83](https://github.com/morluto/rea/commit/6c03f83b1bd55095d136aeb3700733383365ecc4)), closes [#363](https://github.com/morluto/rea/issues/363)
* **pe:** add broader PE/COFF/PDB static inspection ([f942558](https://github.com/morluto/rea/commit/f9425585736a89165390178f245b0f0f5d6cdacf))
* **pe:** add broader PE/COFF/PDB static inspection ([94e6600](https://github.com/morluto/rea/commit/94e6600faf89436e4e2689fda8050792307b268d)), closes [#362](https://github.com/morluto/rea/issues/362)
* **process:** replace procfs sampling with event-backed process-tree capture ([a5e355a](https://github.com/morluto/rea/commit/a5e355a3d52b19e89535449cd923c35e56ccc60d))
* **process:** replace procfs sampling with event-backed process-tree capture ([d5d2e56](https://github.com/morluto/rea/commit/d5d2e56d0461cb0debba540bc658a9938ac30599)), closes [#332](https://github.com/morluto/rea/issues/332)
* **protocol:** add custom TCP/UDP/IPC/XPC and auth-flow capture ([1fb22b4](https://github.com/morluto/rea/commit/1fb22b4c21e3a5581f3928003cc32ddc1cc9530b))
* **protocol:** add custom TCP/UDP/IPC/XPC and auth-flow capture ([6fa6f9b](https://github.com/morluto/rea/commit/6fa6f9b6d9595a480a590766dadcfebb8e7111b5)), closes [#365](https://github.com/morluto/rea/issues/365)
* **protocol:** add gRPC/Protobuf and JSON-RPC/MessagePack capture ([54153ed](https://github.com/morluto/rea/commit/54153ed62cb4f55d1efd4794490c2481ab34e212))
* **protocol:** add gRPC/Protobuf and JSON-RPC/MessagePack capture ([3f336fe](https://github.com/morluto/rea/commit/3f336fefb132971bc6bb37b2b59aa01a5e3be5ca)), closes [#364](https://github.com/morluto/rea/issues/364)
### Bug Fixes
* **catalog:** digest provider projections ([645668b](https://github.com/morluto/rea/commit/645668b70dfdff74582d4ac26cda417947231764))
* **catalog:** digest provider projections ([c4cd033](https://github.com/morluto/rea/commit/c4cd0330e00eeb8e272abbf6ecc6ce961e72f317))
## [2.6.0](https://github.com/morluto/rea/compare/rea-agents-2.5.1...rea-agents-2.6.0) (2026-07-26)
+1 -1
View File
@@ -537,7 +537,7 @@ Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf,
"mcpServers": {
"rea": {
"command": "npx",
"args": ["-y", "rea-agents@2.6.0", "mcp"]
"args": ["-y", "rea-agents@2.7.0", "mcp"]
}
}
}
+1 -1
View File
@@ -183,7 +183,7 @@ rea uninstall --purge-data
"mcpServers": {
"rea": {
"command": "npx",
"args": ["-y", "rea-agents@2.6.0", "mcp"]
"args": ["-y", "rea-agents@2.7.0", "mcp"]
}
}
}
+1 -1
View File
@@ -173,7 +173,7 @@ Setup は Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、Windsurf
"mcpServers": {
"rea": {
"command": "npx",
"args": ["-y", "rea-agents@2.6.0", "mcp"]
"args": ["-y", "rea-agents@2.7.0", "mcp"]
}
}
}
+1 -1
View File
@@ -173,7 +173,7 @@ Setup은 Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin
"mcpServers": {
"rea": {
"command": "npx",
"args": ["-y", "rea-agents@2.6.0", "mcp"]
"args": ["-y", "rea-agents@2.7.0", "mcp"]
}
}
}
+1 -1
View File
@@ -173,7 +173,7 @@ Setup 会检测 Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、Win
"mcpServers": {
"rea": {
"command": "npx",
"args": ["-y", "rea-agents@2.6.0", "mcp"]
"args": ["-y", "rea-agents@2.7.0", "mcp"]
}
}
}
+3 -2
View File
@@ -2,7 +2,7 @@
"catalog_schema_version": 1,
"package": {
"name": "rea-agents",
"version": "2.6.0",
"version": "2.7.0",
"sdk": {
"server": "2.0.0-beta.4",
"client": "2.0.0-beta.4",
@@ -671,7 +671,8 @@
"tools_sha256": "5a88bf598a1e0fe705761db6af92f1ceabaf026cb6efa425e87b9633f1d7a3de",
"prompts_sha256": "f6da3ad38a1000c11364d1710f122ac4990551f04efd8c53ffb2e819b5cf5707",
"resources_sha256": "339a984ea8cd8be5f234adf24395bf0295258d990492005cf6fe1f293d12cd46",
"combined_sha256": "861cd8618e793342daa8b149bc2944360d84b077fd19cf22f6e0a57b6b249c73"
"combined_sha256": "861cd8618e793342daa8b149bc2944360d84b077fd19cf22f6e0a57b6b249c73",
"providers_sha256": "918ccd6b8ae442cd5844dcfde55086f458176241c8d166c1e9dd0f242ccd2bb0"
}
}
}
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "rea-agents",
"version": "2.6.0",
"version": "2.7.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "rea-agents",
"version": "2.6.0",
"version": "2.7.0",
"license": "MIT",
"dependencies": {
"@babel/parser": "8.0.4",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "rea-agents",
"version": "2.6.0",
"version": "2.7.0",
"description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
"license": "MIT",
"repository": {
+11
View File
@@ -1,6 +1,9 @@
import { createHash } from "node:crypto";
import { join } from "node:path";
import { pathToFileURL } from "node:url";
import canonicalize from "canonicalize";
const load = (root, path) => import(pathToFileURL(join(root, path)).href);
/** Sort tool/provider names alphabetically. */
@@ -9,6 +12,14 @@ export const names = (contracts) =>
.map(({ name }) => name)
.sort((left, right) => left.localeCompare(right));
/** Return the stable digest for a generated catalog projection. */
export const digest = (value) => {
const encoded = canonicalize(value);
if (encoded === undefined)
throw new TypeError("Catalog projection is not canonical JSON");
return createHash("sha256").update(encoded).digest("hex");
};
/** Throw when two name lists diverge. */
export const assertSameNames = (label, actual, expected) => {
const actualSet = new Set(actual);
+3
View File
@@ -46,6 +46,9 @@ export interface ProductCatalog {
}
export function createProductCatalog(root: string): Promise<ProductCatalog>;
export function providerCatalogDigest(
providers: ProductCatalog["providers"],
): string;
export function createCliInventory(cli: unknown): {
readonly primary: readonly string[];
readonly aliases: readonly {
+10 -3
View File
@@ -1,6 +1,6 @@
import { format } from "prettier";
import { assertSameNames, loadSources } from "./catalog-core.mjs";
import { assertSameNames, digest, loadSources } from "./catalog-core.mjs";
import {
createCliInventory,
cliCommandDescriptionIssues,
@@ -15,6 +15,9 @@ export {
cliCommandOptionNames,
};
/** Return the stable digest for the source-derived provider projection. */
export const providerCatalogDigest = (providers) => digest(providers);
/** Project current runtime contracts into deterministic, machine-readable facts. */
export const createProductCatalog = async (root) => {
const sources = await loadSources(root);
@@ -25,6 +28,7 @@ export const createProductCatalog = async (root) => {
sources.catalogIdentity.CLI_COMMAND_NAMES,
);
const tools = toolFamilyCatalog(sources);
const providers = providerCatalog(sources);
const metadata = sources.packageMetadata.PACKAGE_METADATA;
return {
catalog_schema_version: 1,
@@ -39,7 +43,7 @@ export const createProductCatalog = async (root) => {
skill_version: metadata.skillVersion,
},
tools,
providers: providerCatalog(sources),
providers,
setup_clients: sources.supportedClients.SUPPORTED_CLIENT_DEFINITIONS.map(
({ name, displayName, format }) => ({
id: name,
@@ -56,7 +60,10 @@ export const createProductCatalog = async (root) => {
},
runtime_catalog: {
counts: sources.catalogIdentity.CATALOG_IDENTITY.counts,
digests: sources.catalogIdentity.CATALOG_IDENTITY.digests,
digests: {
...sources.catalogIdentity.CATALOG_IDENTITY.digests,
providers_sha256: providerCatalogDigest(providers),
},
},
};
};
+206
View File
@@ -0,0 +1,206 @@
import { z } from "zod";
/** Supported managed-runtime bytecode families. */
export const bytecodeFamilySchema = z.enum(["jvm", "python"]);
export type BytecodeFamily = z.infer<typeof bytecodeFamilySchema>;
/** Classification of bytecode provenance. */
export const bytecodeProvenanceSchema = z.enum([
"application",
"generated",
"vendored",
"bundled",
"standard_library",
]);
export type BytecodeProvenance = z.infer<typeof bytecodeProvenanceSchema>;
/** A bytecode symbol discovered through static analysis. */
export const bytecodeSymbolSchema = z.strictObject({
/** Fully qualified name. */
name: z.string().min(1),
/** Raw bytecode location or offset. */
raw_location: z.string().min(1),
/** Normalized symbol type. */
kind: z.enum([
"class",
"interface",
"method",
"field",
"function",
"module",
"variable",
]),
/** Bytecode version if known. */
bytecode_version: z.number().int().nullable(),
/** Provenance classification. */
provenance: bytecodeProvenanceSchema,
/** Whether the symbol is accessible (public). */
is_public: z.boolean().default(false),
});
export type BytecodeSymbol = z.infer<typeof bytecodeSymbolSchema>;
/** A discovered bytecode artifact (class file, wheel, etc). */
export const bytecodeArtifactSchema = z.strictObject({
/** Artifact path relative to the analysis root. */
path: z.string().min(1),
/** Bytecode family. */
family: bytecodeFamilySchema,
/** Artifact format. */
format: z.enum(["class", "jar", "war", "ear", "pyc", "pyo", "whl", "zipapp"]),
/** Size in bytes. */
size: z.number().int().nonnegative(),
/** SHA-256 digest. */
digest: z.string().regex(/^[a-f0-9]{64}$/u),
/** Discovered symbols. */
symbols: z.array(bytecodeSymbolSchema).default([]),
/** Whether this is a standard library artifact. */
is_standard_library: z.boolean().default(false),
/** Whether this is a generated artifact. */
is_generated: z.boolean().default(false),
/** Whether this is a vendored artifact. */
is_vendored: z.boolean().default(false),
});
export type BytecodeArtifact = z.infer<typeof bytecodeArtifactSchema>;
/** Static bytecode analysis result. */
export const bytecodeAnalysisSchema = z.strictObject({
/** Bytecode family. */
family: bytecodeFamilySchema,
/** All discovered artifacts. */
artifacts: z.array(bytecodeArtifactSchema).min(0).max(10_000),
/** Total symbols across all artifacts. */
total_symbols: z.number().int().nonnegative(),
/** Symbols classified as application code. */
application_symbols: z.number().int().nonnegative(),
/** Symbols classified as generated code. */
generated_symbols: z.number().int().nonnegative(),
/** Symbols classified as vendored code. */
vendored_symbols: z.number().int().nonnegative(),
/** Symbols classified as standard library. */
standard_library_symbols: z.number().int().nonnegative(),
});
export type BytecodeAnalysis = z.infer<typeof bytecodeAnalysisSchema>;
/** Detect bytecode family from file extension. */
export function detectBytecodeFamily(path: string): BytecodeFamily | null {
const lower = path.toLowerCase();
if (
lower.endsWith(".class") ||
lower.endsWith(".jar") ||
lower.endsWith(".war") ||
lower.endsWith(".ear")
) {
return "jvm";
}
if (
lower.endsWith(".pyc") ||
lower.endsWith(".pyo") ||
lower.endsWith(".whl") ||
lower.endsWith(".pyz") ||
lower.endsWith(".zipapp")
) {
return "python";
}
return null;
}
/** Detect artifact format from file path. */
export function detectArtifactFormat(
path: string,
): `class` | `jar` | `war` | `ear` | `pyc` | `pyo` | `whl` | `zipapp` | null {
const lower = path.toLowerCase();
if (lower.endsWith(".class")) return "class";
if (lower.endsWith(".jar")) return "jar";
if (lower.endsWith(".war")) return "war";
if (lower.endsWith(".ear")) return "ear";
if (lower.endsWith(".pyc")) return "pyc";
if (lower.endsWith(".pyo")) return "pyo";
if (lower.endsWith(".whl")) return "whl";
if (lower.endsWith(".pyz") || lower.endsWith(".zipapp")) return "zipapp";
return null;
}
/** Classify bytecode symbol provenance. */
export function classifyProvenance(
path: string,
symbolName: string,
): BytecodeProvenance {
const lower = path.toLowerCase();
// Standard library paths
if (
lower.includes("/stdlib/") ||
lower.includes("/site-packages/") ||
lower.includes("java/") ||
lower.includes("javax/") ||
lower.includes("sun/") ||
symbolName.startsWith("java.") ||
symbolName.startsWith("javax.") ||
symbolName.startsWith("sun.") ||
symbolName.startsWith("__")
) {
return "standard_library";
}
// Generated code
if (
lower.includes("/generated/") ||
lower.includes("_generated") ||
lower.includes("/build/") ||
lower.includes("/target/") ||
lower.includes("/dist-packages/") ||
lower.includes("/__pycache__/") ||
symbolName.includes("Generated") ||
symbolName.includes("_generated")
) {
return "generated";
}
// Vendored code
if (
lower.includes("/vendor/") ||
lower.includes("/vendored/") ||
lower.includes("/third_party/") ||
lower.includes("/3rdparty/") ||
lower.includes("/node_modules/") ||
lower.includes("/vendor/")
) {
return "vendored";
}
// Bundled code
if (
lower.includes("/bundle/") ||
lower.includes("/bundled/") ||
lower.includes(".jar!") ||
lower.includes(".war!")
) {
return "bundled";
}
return "application";
}
/** Analyze a set of bytecode artifacts and produce a summary. */
export function analyzeBytecodeArtifacts(
artifacts: readonly BytecodeArtifact[],
family: BytecodeFamily,
): BytecodeAnalysis {
const applicationSymbols = artifacts
.flatMap((a) => a.symbols)
.filter((s) => s.provenance === "application").length;
const generatedSymbols = artifacts
.flatMap((a) => a.symbols)
.filter((s) => s.provenance === "generated").length;
const vendoredSymbols = artifacts
.flatMap((a) => a.symbols)
.filter((s) => s.provenance === "vendored").length;
const standardLibrarySymbols = artifacts
.flatMap((a) => a.symbols)
.filter((s) => s.provenance === "standard_library").length;
return {
family,
artifacts: artifacts.slice(0, 10_000),
total_symbols: artifacts.reduce((sum, a) => sum + a.symbols.length, 0),
application_symbols: applicationSymbols,
generated_symbols: generatedSymbols,
vendored_symbols: vendoredSymbols,
standard_library_symbols: standardLibrarySymbols,
};
}
+218
View File
@@ -0,0 +1,218 @@
import { createHash } from "node:crypto";
import canonicalize from "canonicalize";
import { z } from "zod";
import { evidenceEnvelopeSchema } from "./evidence.js";
import { evidenceBundleSchema } from "./evidenceBundle.js";
/** Schema version for the conformance package format. */
export const CONFORMANCE_PACKAGE_VERSION = 1;
/** A stable, path-independent identifier for a conformance package. */
export const conformancePackageIdSchema = z
.string()
.regex(/^cp_[a-f0-9]{64}$/u);
/** Identifier for a single scenario within a package. */
export const scenarioIdSchema = z
.string()
.regex(/^[A-Za-z][A-Za-z0-9._-]{0,99}$/u);
/** Deterministic manifest for a scenario fixture. */
export const scenarioManifestSchema = z.strictObject({
scenario_id: scenarioIdSchema,
name: z.string().min(1),
description: z.string().min(1),
/** Source-owned fixture path relative to the repository root. */
fixture_path: z.string().min(1),
/** Expected exit code or null if unspecified. */
expected_exit_code: z.number().int().nullable(),
/** Expected output patterns that must appear in the capture. */
expected_patterns: z.array(z.string()).default([]),
});
/** Replay plan describing how a scenario is replayed deterministically. */
export const replayPlanSchema = z.strictObject({
scenario_id: scenarioIdSchema,
/** Ordered steps to execute during replay. */
steps: z
.array(
z.strictObject({
step_id: z.string().min(1),
action: z.string().min(1),
arguments: z.array(z.string()).default([]),
timeout_ms: z.number().int().positive(),
}),
)
.min(1)
.max(100),
/** Environment variables to set (never inherit host paths). */
environment: z.record(z.string(), z.string()).default({}),
});
/** Shim plan for intercepting observable effects. */
export const shimPlanSchema = z.strictObject({
scenario_id: scenarioIdSchema,
/** Shims to install, each intercepting a named effect. */
shims: z
.array(
z.strictObject({
shim_id: z.string().min(1),
kind: z.enum(["filesystem", "network", "process", "signal"]),
target: z.string().min(1),
policy: z.enum(["observe", "allow", "block", "emulate"]),
}),
)
.min(0)
.max(50),
});
/** Expected evidence for a scenario, checked against the captured run. */
export const expectedEvidenceSchema = z.strictObject({
scenario_id: scenarioIdSchema,
/** Expected evidence envelopes. */
envelopes: z.array(evidenceEnvelopeSchema).min(0).max(100),
/** Expected evidence bundle. */
bundle: evidenceBundleSchema.nullable(),
/** Required dimensions that must be present in the evidence. */
required_dimensions: z.array(z.string().min(1)).default([]),
});
/** Verifier contract describing how to validate conformance. */
export const verifierContractSchema = z.strictObject({
scenario_id: scenarioIdSchema,
/** Dimensions to verify. */
dimensions: z
.array(
z.strictObject({
name: z.string().min(1),
required: z.boolean().default(true),
comparison: z.enum(["exact", "semantic", "fuzzy"]),
}),
)
.min(1)
.max(50),
/** Tolerance for timing differences in milliseconds. */
timing_tolerance_ms: z.number().int().nonnegative().default(0),
});
/** Top-level conformance package manifest. */
export const conformancePackageSchema = z.strictObject({
schema_version: z.literal(CONFORMANCE_PACKAGE_VERSION),
package_id: conformancePackageIdSchema,
name: z.string().min(1),
description: z.string().min(1),
created_at: z.string().datetime(),
/** Scenario manifests. */
scenarios: z.array(scenarioManifestSchema).min(1).max(100),
/** Replay plans keyed by scenario_id. */
replay_plans: z.array(replayPlanSchema).min(1).max(100),
/** Shim plans keyed by scenario_id. */
shim_plans: z.array(shimPlanSchema).default([]),
/** Expected evidence for each scenario. */
expected_evidence: z.array(expectedEvidenceSchema).min(1).max(100),
/** Verifier contracts for each scenario. */
verifier_contracts: z.array(verifierContractSchema).min(1).max(100),
});
export type ConformancePackage = z.infer<typeof conformancePackageSchema>;
export type ScenarioManifest = z.infer<typeof scenarioManifestSchema>;
export type ReplayPlan = z.infer<typeof replayPlanSchema>;
export type ShimPlan = z.infer<typeof shimPlanSchema>;
export type ExpectedEvidence = z.infer<typeof expectedEvidenceSchema>;
export type VerifierContract = z.infer<typeof verifierContractSchema>;
/** Error from validation or package operations. */
export type ConformancePackageError =
| { kind: "invalid_package"; message: string }
| { kind: "scenario_not_found"; scenario_id: string }
| { kind: "duplicate_scenario"; scenario_id: string };
/** Result type for package operations. */
export type ConformancePackageResult<T> =
| { ok: true; value: T }
| { ok: false; error: ConformancePackageError };
/** Validate a conformance package and cross-check internal references. */
export function validateConformancePackage(
input: unknown,
): ConformancePackageResult<ConformancePackage> {
const parsed = conformancePackageSchema.safeParse(input);
if (!parsed.success)
return {
ok: false,
error: {
kind: "invalid_package",
message: parsed.error.issues[0]?.message ?? "invalid package",
},
};
const pkg = parsed.data;
// Check for duplicate scenario IDs
const seen = new Set<string>();
for (const s of pkg.scenarios) {
if (seen.has(s.scenario_id))
return {
ok: false,
error: { kind: "duplicate_scenario", scenario_id: s.scenario_id },
};
seen.add(s.scenario_id);
}
// Check that replay plans reference existing scenarios
for (const rp of pkg.replay_plans) {
if (!seen.has(rp.scenario_id))
return {
ok: false,
error: {
kind: "scenario_not_found",
scenario_id: rp.scenario_id,
},
};
}
// Check that expected evidence references existing scenarios
for (const ee of pkg.expected_evidence) {
if (!seen.has(ee.scenario_id))
return {
ok: false,
error: {
kind: "scenario_not_found",
scenario_id: ee.scenario_id,
},
};
}
// Check that verifier contracts reference existing scenarios
for (const vc of pkg.verifier_contracts) {
if (!seen.has(vc.scenario_id))
return {
ok: false,
error: {
kind: "scenario_not_found",
scenario_id: vc.scenario_id,
},
};
}
return { ok: true, value: pkg };
}
/** Compute a deterministic package ID from the canonical JSON. */
export function computePackageId(
pkg: Omit<ConformancePackage, "package_id">,
): string {
const json = canonicalize(pkg);
if (!json) throw new Error("failed to canonicalize package");
return `cp_${createHash("sha256").update(json).digest("hex")}`;
}
/** Create a conformance package with an auto-computed package_id. */
export function createConformancePackage(
pkg: Omit<ConformancePackage, "package_id">,
): ConformancePackage {
const package_id = computePackageId(pkg);
return { package_id, ...pkg };
}
+138
View File
@@ -0,0 +1,138 @@
import { z } from "zod";
import {
conformancePackageSchema,
type ConformancePackage,
} from "./conformancePackage.js";
import { trustGateResultSchema } from "./conformanceTrustGate.js";
/** Result of a single scenario replay. */
export const scenarioReplayResultSchema = z.strictObject({
scenario_id: z.string().min(1),
status: z.enum(["pass", "fail", "error", "skipped"]),
exit_code: z.number().int().nullable(),
duration_ms: z.number().int().nonnegative(),
output: z.string().default(""),
error: z.string().nullable(),
});
/** Result of replaying an entire conformance package. */
export const packageReplayResultSchema = z.strictObject({
package_id: z.string().min(1),
total_scenarios: z.number().int().positive(),
passed: z.number().int().nonnegative(),
failed: z.number().int().nonnegative(),
errored: z.number().int().nonnegative(),
skipped: z.number().int().nonnegative(),
scenario_results: z.array(scenarioReplayResultSchema),
trust_gate_results: z.array(trustGateResultSchema),
drift_detected: z.boolean(),
first_drift: z
.strictObject({
scenario_id: z.string().min(1),
dimension: z.string().min(1),
message: z.string(),
})
.nullable(),
});
export type ScenarioReplayResult = z.infer<typeof scenarioReplayResultSchema>;
export type PackageReplayResult = z.infer<typeof packageReplayResultSchema>;
/** Callback interface for replaying a scenario. */
export interface ScenarioRunner {
(scenarioId: string, fixturePath: string): Promise<ScenarioReplayResult>;
}
/**
* Default no-op scenario runner that skips all scenarios.
* Real CI replays inject an actual runner.
*/
async function defaultRunner(): Promise<ScenarioReplayResult> {
return {
scenario_id: "unknown",
status: "skipped",
exit_code: null,
duration_ms: 0,
output: "",
error: "no runner provided",
};
}
/**
* Replay a conformance package from a clean checkout.
* Runs each scenario, evaluates trust gates, and detects drift
* between the captured run and the committed package.
*/
export async function replayConformancePackage(
packageInput: unknown,
actualEvidence: Record<string, Record<string, unknown>>,
runner: ScenarioRunner = defaultRunner,
options: { truncated?: boolean } = {},
): Promise<PackageReplayResult> {
const parsed = conformancePackageSchema.safeParse(packageInput);
if (!parsed.success)
throw new TypeError(
`invalid conformance package: ${parsed.error.issues[0]?.message ?? "unknown"}`,
);
const pkg: ConformancePackage = parsed.data;
const scenarioResults: ScenarioReplayResult[] = [];
let passed = 0;
let failed = 0;
let errored = 0;
let skipped = 0;
for (const scenario of pkg.scenarios) {
const result = await runner(scenario.scenario_id, scenario.fixture_path);
scenarioResults.push(result);
switch (result.status) {
case "pass":
passed++;
break;
case "fail":
failed++;
break;
case "error":
errored++;
break;
case "skipped":
skipped++;
break;
}
}
const trustGateResults = evaluatePackageTrustGates(
pkg,
actualEvidence,
options,
);
const driftGates = trustGateResults.filter((r) => r.verdict === "fail");
const drift_detected = driftGates.length > 0;
const first_drift_gate = driftGates[0];
const first_drift = first_drift_gate?.first_divergence
? {
scenario_id: first_drift_gate.scenario_id,
dimension: first_drift_gate.first_divergence.dimension,
message: first_drift_gate.first_divergence.message,
}
: null;
return {
package_id: pkg.package_id,
total_scenarios: pkg.scenarios.length,
passed,
failed,
errored,
skipped,
scenario_results: scenarioResults,
trust_gate_results: trustGateResults,
drift_detected,
first_drift,
};
}
/** Import trust gate evaluator for replay. */
import { evaluatePackageTrustGates } from "./conformanceTrustGate.js";
+246
View File
@@ -0,0 +1,246 @@
import { z } from "zod";
import type {
ConformancePackage,
VerifierContract,
} from "./conformancePackage.js";
/** Result of comparing a single dimension. */
export const dimensionResultSchema = z.strictObject({
name: z.string().min(1),
status: z.enum(["match", "mismatch", "unknown", "truncated"]),
message: z.string().default(""),
evidence_ids: z.array(z.string()).default([]),
});
/** Result of evaluating a trust gate for one scenario. */
export const trustGateResultSchema = z.strictObject({
scenario_id: z.string().min(1),
verdict: z.enum(["pass", "fail", "unknown"]),
dimension_results: z.array(dimensionResultSchema),
first_divergence: z
.strictObject({
dimension: z.string().min(1),
evidence_id: z.string().min(1),
message: z.string(),
})
.nullable(),
});
export type DimensionResult = z.infer<typeof dimensionResultSchema>;
export type TrustGateResult = z.infer<typeof trustGateResultSchema>;
/** Dimension that is volatile due to timing or normalization. */
const VOLATILE_DIMENSIONS = new Set([
"timing",
"timestamp",
"pid",
"ppid",
"duration_ms",
"created_at",
"updated_at",
]);
/** Dimension that carries semantic content. */
const SEMANTIC_DIMENSIONS = new Set([
"exit_code",
"stdout",
"stderr",
"filesystem",
"process_tree",
"shim_events",
"protocol_events",
"event_journal",
]);
/** Check if a dimension name is volatile (timing/normalization noise). */
export function isVolatileDimension(name: string): boolean {
return VOLATILE_DIMENSIONS.has(name);
}
/** Check if a dimension name carries semantic content. */
export function isSemanticDimension(name: string): boolean {
return SEMANTIC_DIMENSIONS.has(name);
}
/**
* Compare two values for a dimension, classifying semantic diffs
* from timing/normalization noise.
*
* Volatile dimensions (timing, timestamps, PIDs) are always treated
* as matches because their values are expected to differ across
* runs and do not carry semantic meaning.
*/
export function compareDimension(
dimensionName: string,
expected: unknown,
actual: unknown,
options: { truncated?: boolean } = {},
): DimensionResult {
// Volatile dimensions: always match regardless of values
if (isVolatileDimension(dimensionName)) {
return {
name: dimensionName,
status: "match",
message: "volatile dimension ignored",
evidence_ids: [],
};
}
if (options.truncated) {
return {
name: dimensionName,
status: "truncated",
message: "evidence was truncated",
evidence_ids: [],
};
}
if (expected === undefined && actual === undefined) {
return {
name: dimensionName,
status: "unknown",
message: "both expected and actual are undefined",
evidence_ids: [],
};
}
if (expected === undefined || actual === undefined) {
return {
name: dimensionName,
status: "mismatch",
message: `expected ${expected === undefined ? "present" : "absent"}, actual ${actual === undefined ? "absent" : "present"}`,
evidence_ids: [],
};
}
// Semantic comparison for structured objects
if (typeof expected === "object" && typeof actual === "object") {
const expectedJson = JSON.stringify(sortKeys(expected));
const actualJson = JSON.stringify(sortKeys(actual));
if (expectedJson === actualJson) {
return {
name: dimensionName,
status: "match",
message: "",
evidence_ids: [],
};
}
return {
name: dimensionName,
status: "mismatch",
message: "semantic content differs",
evidence_ids: [],
};
}
// Primitive comparison
if (expected === actual) {
return {
name: dimensionName,
status: "match",
message: "",
evidence_ids: [],
};
}
return {
name: dimensionName,
status: "mismatch",
message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
evidence_ids: [],
};
}
/** Recursively sort object keys for deterministic comparison. */
function sortKeys(value: unknown): unknown {
if (value === null || typeof value !== "object") return value;
if (Array.isArray(value)) return value.map(sortKeys);
const sorted: Record<string, unknown> = {};
for (const key of Object.keys(value as Record<string, unknown>).sort()) {
sorted[key] = sortKeys((value as Record<string, unknown>)[key]);
}
return sorted;
}
/**
* Evaluate a trust gate for one scenario by comparing expected
* evidence against the actual captured run.
*/
export function evaluateTrustGate(
contract: VerifierContract,
expectedEvidence: Record<string, unknown>,
actualEvidence: Record<string, unknown>,
options: { truncated?: boolean } = {},
): TrustGateResult {
const dimensionResults: DimensionResult[] = [];
let firstDivergence: TrustGateResult["first_divergence"] = null;
for (const dim of contract.dimensions) {
if (!dim.required) continue;
const expectedValue = expectedEvidence[dim.name];
const actualValue = actualEvidence[dim.name];
const result = compareDimension(
dim.name,
expectedValue,
actualValue,
options,
);
dimensionResults.push(result);
if (result.status === "mismatch" && firstDivergence === null) {
firstDivergence = {
dimension: dim.name,
evidence_id: result.evidence_ids[0] ?? "unknown",
message: result.message,
};
}
}
const hasFail = dimensionResults.some(
(r) => r.status === "mismatch" || r.status === "truncated",
);
const hasUnknown = dimensionResults.some((r) => r.status === "unknown");
const verdict: TrustGateResult["verdict"] = hasFail
? "fail"
: hasUnknown
? "unknown"
: "pass";
return {
scenario_id: contract.scenario_id,
verdict,
dimension_results: dimensionResults,
first_divergence: firstDivergence,
};
}
/**
* Evaluate trust gates for all scenarios in a conformance package.
* Rejects runs that differ in required dimensions. Unknown/truncated
* evidence is never treated as equivalence.
*/
export function evaluatePackageTrustGates(
pkg: ConformancePackage,
actualEvidence: Record<string, Record<string, unknown>>,
options: { truncated?: boolean } = {},
): TrustGateResult[] {
const results: TrustGateResult[] = [];
for (const contract of pkg.verifier_contracts) {
const expected = pkg.expected_evidence.find(
(e) => e.scenario_id === contract.scenario_id,
);
if (!expected) continue;
const expectedEvidence = expected.envelopes[0] ?? {};
const actual = actualEvidence[contract.scenario_id] ?? {};
const result = evaluateTrustGate(
contract,
expectedEvidence as Record<string, unknown>,
actual,
options,
);
results.push(result);
}
return results;
}
+173
View File
@@ -0,0 +1,173 @@
import { z } from "zod";
import { jsonValueSchema } from "./jsonValue.js";
/** Supported transport types for custom protocol capture. */
export const transportTypeSchema = z.enum([
"tcp",
"udp",
"ipc",
"unix-socket",
"named-pipe",
"xpc",
]);
export type TransportType = z.infer<typeof transportTypeSchema>;
/** Direction of a protocol frame. */
export const frameDirectionSchema = z.enum(["sent", "received", "intercepted"]);
export type FrameDirection = z.infer<typeof frameDirectionSchema>;
/** A captured protocol frame. */
export const protocolFrameSchema = z.strictObject({
/** Monotonic sequence number. */
sequence: z.number().int().nonnegative(),
/** Timestamp in milliseconds. */
at_ms: z.number().int().nonnegative(),
/** Transport type. */
transport: transportTypeSchema,
/** Direction of the frame. */
direction: frameDirectionSchema,
/** Source process identity. */
source_pid: z.number().int().nullable(),
/** Destination process identity. */
dest_pid: z.number().int().nullable(),
/** Endpoint address (IP:port, socket path, pipe name). */
source_endpoint: z.string().nullable(),
/** Destination endpoint. */
dest_endpoint: z.string().nullable(),
/** Raw frame data as base64. */
raw_data: z.string().nullable(),
/** Decoded/parsed frame content if known. */
decoded_content: jsonValueSchema.nullable(),
/** Frame size in bytes. */
size: z.number().int().nonnegative(),
/** Whether the frame was truncated. */
truncated: z.boolean().default(false),
});
export type ProtocolFrame = z.infer<typeof protocolFrameSchema>;
/** Authentication flow stage. */
export const authStageSchema = z.enum([
"init",
"challenge",
"response",
"token_exchange",
"renewal",
"revocation",
"failure",
"success",
]);
export type AuthStage = z.infer<typeof authStageSchema>;
/** Token lifecycle event. */
export const tokenLifecycleEventSchema = z.enum([
"issued",
"refreshed",
"expired",
"revoked",
"renewed",
]);
export type TokenLifecycleEvent = z.infer<typeof tokenLifecycleEventSchema>;
/** A captured authentication flow event. */
export const authFlowEventSchema = z.strictObject({
/** Monotonic sequence number. */
sequence: z.number().int().nonnegative(),
/** Timestamp in milliseconds. */
at_ms: z.number().int().nonnegative(),
/** Authentication stage. */
stage: authStageSchema,
/** Protocol used. */
protocol: z.string().min(1),
/** Token type if applicable. */
token_type: z.string().nullable(),
/** Token lifecycle event. */
token_lifecycle: tokenLifecycleEventSchema.nullable(),
/** Correlation ID linking challenge-response pairs. */
correlation_id: z.string().nullable(),
/** Whether credentials were detected and redacted. */
credentials_redacted: z.boolean().default(false),
/** Whether the authentication succeeded. */
succeeded: z.boolean().default(false),
/** Error message if authentication failed. */
error: z.string().nullable(),
});
export type AuthFlowEvent = z.infer<typeof authFlowEventSchema>;
/** A captured protocol session. */
export const customProtocolCaptureSchema = z.strictObject({
/** Transport type for this session. */
transport: transportTypeSchema,
/** Captured frames in order. */
frames: z.array(protocolFrameSchema).min(0).max(100_000),
/** Authentication flow events. */
auth_events: z.array(authFlowEventSchema).default([]),
/** Whether any frame was truncated. */
has_truncated: z.boolean().default(false),
/** Whether credentials were detected. */
credentials_detected: z.boolean().default(false),
});
export type CustomProtocolCapture = z.infer<typeof customProtocolCaptureSchema>;
/** Correlate a frame with process identity. */
export function correlateProcessIdentity(
frame: ProtocolFrame,
pid: number,
): boolean {
return frame.source_pid === pid || frame.dest_pid === pid;
}
/** Check if a frame contains credential-like content. */
export function looksLikeCredentialFrame(frame: ProtocolFrame): boolean {
const patterns = [
"password",
"token",
"secret",
"api_key",
"apikey",
"authorization",
"credential",
];
const content = JSON.stringify(frame.decoded_content ?? "").toLowerCase();
return patterns.some((p) => content.includes(p));
}
/** Filter frames by transport type. */
export function framesByTransport(
frames: readonly ProtocolFrame[],
transport: TransportType,
): ProtocolFrame[] {
return frames.filter((f) => f.transport === transport);
}
/** Get all authentication flow events for a specific protocol. */
export function authEventsByProtocol(
events: readonly AuthFlowEvent[],
protocol: string,
): AuthFlowEvent[] {
return events.filter((e) => e.protocol === protocol);
}
/** Get successful authentication events. */
export function successfulAuthEvents(
events: readonly AuthFlowEvent[],
): AuthFlowEvent[] {
return events.filter((e) => e.succeeded);
}
/** Get failed authentication events. */
export function failedAuthEvents(
events: readonly AuthFlowEvent[],
): AuthFlowEvent[] {
return events.filter((e) => !e.succeeded);
}
/** Compute the duration of an authentication flow in milliseconds. */
export function authFlowDuration(
events: readonly AuthFlowEvent[],
): number | null {
if (events.length === 0) return null;
const first = events[0]!;
const last = events[events.length - 1]!;
return last.at_ms - first.at_ms;
}
+240
View File
@@ -0,0 +1,240 @@
import { z } from "zod";
/** Event types for event-backed process-tree capture. */
export const processEventTypeSchema = z.enum([
"spawn",
"exit",
"re_exec",
"reparent",
"signal",
"name_change",
"thread_create",
"thread_exit",
]);
export type ProcessEventType = z.infer<typeof processEventTypeSchema>;
/** A single event-backed process-tree event. */
export const processTreeEventSchema = z.strictObject({
/** Monotonic event sequence number. */
sequence: z.number().int().nonnegative(),
/** Event timestamp in milliseconds. */
at_ms: z.number().int().nonnegative(),
/** Event type. */
type: processEventTypeSchema,
/** Process ID. */
pid: z.number().int().positive(),
/** Parent process ID. */
ppid: z.number().int().nullable(),
/** Process name if known. */
process_name: z.string().nullable(),
/** Executable path if known. */
executable: z.string().nullable(),
/** Command line arguments. */
arguments: z.array(z.string()).default([]),
/** Previous PID (for reparent events). */
previous_pid: z.number().int().nullable(),
/** Previous PPID (for reparent events). */
previous_ppid: z.number().int().nullable(),
/** Exit code (for exit events). */
exit_code: z.number().int().nullable(),
/** Signal number (for signal events). */
signal: z.number().int().nullable(),
/** Thread ID (for thread events). */
tid: z.number().int().nullable(),
});
export type ProcessTreeEvent = z.infer<typeof processTreeEventSchema>;
/** Process node in a reconstructed tree. */
export const processNodeSchema = z.strictObject({
pid: z.number().int().positive(),
ppid: z.number().int().nullable(),
process_name: z.string().nullable(),
executable: z.string().nullable(),
arguments: z.array(z.string()).default([]),
children: z.array(z.number().int()).default([]),
spawn_time_ms: z.number().int().nullable(),
exit_time_ms: z.number().int().nullable(),
exit_code: z.number().int().nullable(),
is_re_exec: z.boolean().default(false),
is_reparented: z.boolean().default(false),
previous_ppid: z.number().int().nullable(),
});
export type ProcessNode = z.infer<typeof processNodeSchema>;
/** Result of event-backed process-tree reconstruction. */
export const processTreeReconstructionSchema = z.strictObject({
/** Root PID of the process tree. */
root_pid: z.number().int().positive(),
/** All reconstructed process nodes. */
processes: z.array(processNodeSchema).min(0).max(10_000),
/** Events that were consumed. */
events_consumed: z.number().int().nonnegative(),
/** Events that could not be matched. */
events_unmatched: z.number().int().nonnegative(),
/** Short-lived descendants that were missed by sampling. */
short_lived_descendants: z.number().int().nonnegative(),
/** Whether any re-exec was detected. */
has_re_exec: z.boolean().default(false),
/** Whether any reparenting was detected. */
has_reparenting: z.boolean().default(false),
});
export type ProcessTreeReconstruction = z.infer<
typeof processTreeReconstructionSchema
>;
/** Reconstruct a process tree from event-backed capture. */
export function reconstructProcessTree(
events: readonly ProcessTreeEvent[],
rootPid: number,
): ProcessTreeReconstruction {
const nodes = new Map<number, ProcessNode>();
const children = new Map<number, number[]>();
let eventsConsumed = 0;
let eventsUnmatched = 0;
let hasReExec = false;
let hasReparenting = false;
let shortLivedDescendants = 0;
const sorted = [...events].sort((a, b) => a.at_ms - b.at_ms);
for (const event of sorted) {
eventsConsumed++;
let node = nodes.get(event.pid);
switch (event.type) {
case "spawn": {
if (!node) {
node = {
pid: event.pid,
ppid: event.ppid,
process_name: event.process_name,
executable: event.executable,
arguments: event.arguments,
children: [],
spawn_time_ms: event.at_ms,
exit_time_ms: null,
exit_code: null,
is_re_exec: false,
is_reparented: false,
previous_ppid: null,
};
nodes.set(event.pid, node);
}
if (event.ppid !== null) {
const parentChildren = children.get(event.ppid) ?? [];
parentChildren.push(event.pid);
children.set(event.ppid, parentChildren);
}
break;
}
case "exit": {
if (node) {
node.exit_time_ms = event.at_ms;
node.exit_code = event.exit_code;
if (
node.spawn_time_ms !== null &&
event.at_ms - node.spawn_time_ms < 100
)
shortLivedDescendants++;
} else {
eventsUnmatched++;
}
break;
}
case "re_exec": {
if (node) {
node.is_re_exec = true;
node.executable = event.executable ?? node.executable;
node.arguments = event.arguments;
hasReExec = true;
} else {
eventsUnmatched++;
}
break;
}
case "reparent": {
if (node) {
node.previous_ppid = node.ppid;
node.ppid = event.ppid;
node.is_reparented = true;
hasReparenting = true;
} else {
eventsUnmatched++;
}
break;
}
case "signal":
case "name_change":
case "thread_create":
case "thread_exit":
// These events are recorded but don't modify the tree structure
break;
}
}
// Attach children to nodes
for (const [pid, childPids] of children) {
const node = nodes.get(pid);
if (node) node.children = childPids;
}
return {
root_pid: rootPid,
processes: [...nodes.values()],
events_consumed: eventsConsumed,
events_unmatched: eventsUnmatched,
short_lived_descendants: shortLivedDescendants,
has_re_exec: hasReExec,
has_reparenting: hasReparenting,
};
}
/** Get all descendant PIDs of a given root PID. */
export function getDescendants(
processes: readonly ProcessNode[],
rootPid: number,
): number[] {
const byPid = new Map(processes.map((p) => [p.pid, p]));
const visited = new Set<number>();
const result: number[] = [];
const queue: number[] = [rootPid];
while (queue.length > 0) {
const pid = queue.shift()!;
if (visited.has(pid)) continue;
visited.add(pid);
const node = byPid.get(pid);
if (node) {
for (const child of node.children) {
if (!visited.has(child)) {
result.push(child);
queue.push(child);
}
}
}
}
return result;
}
/** Check if a process tree contains a specific PID. */
export function containsProcess(
processes: readonly ProcessNode[],
pid: number,
): boolean {
return processes.some((p) => p.pid === pid);
}
/** Get the maximum tree depth from the root. */
export function maxTreeDepth(
processes: readonly ProcessNode[],
rootPid: number,
): number {
const byPid = new Map(processes.map((p) => [p.pid, p]));
function depth(pid: number, visited: Set<number>): number {
if (visited.has(pid)) return 0;
visited.add(pid);
const node = byPid.get(pid);
if (!node || node.children.length === 0) return 0;
return 1 + Math.max(...node.children.map((c) => depth(c, visited)));
}
return depth(rootPid, new Set());
}
@@ -0,0 +1,179 @@
import { z } from "zod";
/** Supported mobile artifact formats. */
export const mobileArtifactFormatSchema = z.enum([
"apk",
"aab",
"ipa",
"dex",
"native_lib",
]);
export type MobileArtifactFormat = z.infer<typeof mobileArtifactFormatSchema>;
/** Mobile platform. */
export const mobilePlatformSchema = z.enum([
"android",
"ios",
"cross_platform",
]);
export type MobilePlatform = z.infer<typeof mobilePlatformSchema>;
/** Android manifest entry. */
export const androidManifestSchema = z.strictObject({
package_name: z.string().min(1),
version_name: z.string().nullable(),
version_code: z.number().int().nullable(),
min_sdk: z.number().int().nullable(),
target_sdk: z.number().int().nullable(),
permissions: z.array(z.string()).default([]),
activities: z.array(z.string()).default([]),
services: z.array(z.string()).default([]),
receivers: z.array(z.string()).default([]),
providers: z.array(z.string()).default([]),
});
export type AndroidManifest = z.infer<typeof androidManifestSchema>;
/** iOS app manifest (Info.plist). */
export const iosManifestSchema = z.strictObject({
bundle_identifier: z.string().min(1),
bundle_version: z.string().nullable(),
short_version: z.string().nullable(),
minimum_os_version: z.string().nullable(),
supported_platforms: z.array(z.string()).default([]),
ui_required_device_capabilities: z.array(z.string()).default([]),
app_permissions: z.array(z.string()).default([]),
});
export type IosManifest = z.infer<typeof iosManifestSchema>;
/** Signing information. */
export const signingInfoSchema = z.strictObject({
is_signed: z.boolean().default(false),
signer_identity: z.string().nullable(),
certificate_fingerprint: z.string().nullable(),
signature_scheme: z.string().nullable(),
is_debuggable: z.boolean().default(false),
});
export type SigningInfo = z.infer<typeof signingInfoSchema>;
/** Native library entry. */
export const nativeLibrarySchema = z.strictObject({
path: z.string().min(1),
architecture: z.string().nullable(),
size: z.number().int().nonnegative(),
digest: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.nullable(),
});
export type NativeLibrary = z.infer<typeof nativeLibrarySchema>;
/** Resource entry within a mobile artifact. */
export const mobileResourceSchema = z.strictObject({
path: z.string().min(1),
type: z.enum([
"layout",
"drawable",
"string",
"asset",
"raw",
"native_lib",
"manifest",
"entitlements",
"provisioning",
"other",
]),
size: z.number().int().nonnegative(),
});
export type MobileResource = z.infer<typeof mobileResourceSchema>;
/** Static analysis result for a mobile artifact. */
export const mobileArtifactManifestSchema = z.strictObject({
format: mobileArtifactFormatSchema,
platform: mobilePlatformSchema,
app_name: z.string().nullable(),
android_manifest: androidManifestSchema.nullable(),
ios_manifest: iosManifestSchema.nullable(),
signing: signingInfoSchema,
resources: z.array(mobileResourceSchema).default([]),
native_libraries: z.array(nativeLibrarySchema).default([]),
total_size: z.number().int().nonnegative(),
architectures: z.array(z.string()).default([]),
});
export type MobileArtifactManifest = z.infer<
typeof mobileArtifactManifestSchema
>;
/** Detect mobile artifact format from file extension. */
export function detectMobileFormat(path: string): MobileArtifactFormat | null {
const lower = path.toLowerCase();
if (lower.endsWith(".apk")) return "apk";
if (lower.endsWith(".aab")) return "aab";
if (lower.endsWith(".ipa")) return "ipa";
if (lower.endsWith(".dex")) return "dex";
if (lower.endsWith(".so") || lower.endsWith(".dylib") || lower.endsWith(".a"))
return "native_lib";
return null;
}
/** Detect platform from format. */
export function detectPlatform(format: MobileArtifactFormat): MobilePlatform {
switch (format) {
case "apk":
case "aab":
case "dex":
return "android";
case "ipa":
return "ios";
case "native_lib":
return "cross_platform";
}
}
/** Classify a resource by its path. */
export function classifyMobileResource(path: string): MobileResource["type"] {
const lower = path.toLowerCase();
if (lower.includes("androidmanifest.xml")) return "manifest";
if (lower.includes(".entitlements")) return "entitlements";
if (lower.includes("provisioning") || lower.includes(".mobileprovision"))
return "provisioning";
if (lower.includes("/layout/")) return "layout";
if (lower.includes("/drawable/") || lower.includes("/mipmap/"))
return "drawable";
if (lower.includes("/values/")) return "string";
if (lower.includes("assets/") || lower.includes("raw/")) return "asset";
if (lower.endsWith(".so") || lower.endsWith(".dylib")) return "native_lib";
if (lower.endsWith(".xml")) return "layout";
return "other";
}
/** Get all native libraries for a specific architecture. */
export function nativeLibsByArchitecture(
manifest: MobileArtifactManifest,
arch: string,
): NativeLibrary[] {
return manifest.native_libraries.filter((l) => l.architecture === arch);
}
/** Check if an Android artifact has internet permission. */
export function hasInternetPermission(
manifest: MobileArtifactManifest,
): boolean {
if (!manifest.android_manifest) return false;
return manifest.android_manifest.permissions.some(
(p) => p.includes("INTERNET") || p.includes("android.permission.INTERNET"),
);
}
/** Get all unique architectures across native libraries. */
export function getAllArchitectures(
manifest: MobileArtifactManifest,
): string[] {
const archs = new Set<string>();
for (const lib of manifest.native_libraries) {
if (lib.architecture) archs.add(lib.architecture);
}
for (const arch of manifest.architectures) {
archs.add(arch);
}
return [...archs];
}
+192
View File
@@ -0,0 +1,192 @@
import { z } from "zod";
/** Objective-C method type. */
export const objcMethodTypeSchema = z.enum([
"instance",
"class",
"ivar_getter",
"ivar_setter",
]);
export type ObjcMethodType = z.infer<typeof objcMethodTypeSchema>;
/** Objective-C property attribute. */
export const objcPropertyAttributeSchema = z.strictObject({
name: z.string().min(1),
value: z.string(),
is_weak: z.boolean().default(false),
is_atomic: z.boolean().default(false),
is_copy: z.boolean().default(false),
is_strong: z.boolean().default(false),
});
export type ObjcPropertyAttribute = z.infer<typeof objcPropertyAttributeSchema>;
/** Objective-C method metadata. */
export const objcMethodSchema = z.strictObject({
selector: z.string().min(1),
method_type: objcMethodTypeSchema,
address: z.number().int().nullable(),
is_required: z.boolean().default(false),
is_optional: z.boolean().default(false),
});
export type ObjcMethod = z.infer<typeof objcMethodSchema>;
/** Objective-C property metadata. */
export const objcPropertySchema = z.strictObject({
name: z.string().min(1),
type_encoding: z.string().nullable(),
attributes: z.array(objcPropertyAttributeSchema).default([]),
is_readonly: z.boolean().default(false),
getter: z.string().nullable(),
setter: z.string().nullable(),
});
export type ObjcProperty = z.infer<typeof objcPropertySchema>;
/** Objective-C protocol metadata. */
export const objcProtocolSchema = z.strictObject({
name: z.string().min(1),
methods: z.array(objcMethodSchema).default([]),
optional_methods: z.array(objcMethodSchema).default([]),
properties: z.array(objcPropertySchema).default([]),
});
export type ObjcProtocol = z.infer<typeof objcProtocolSchema>;
/** Objective-C class metadata. */
export const objcClassSchema = z.strictObject({
name: z.string().min(1),
super_class: z.string().nullable(),
is_meta_class: z.boolean().default(false),
is_root_class: z.boolean().default(false),
methods: z.array(objcMethodSchema).default([]),
properties: z.array(objcPropertySchema).default([]),
protocols: z.array(z.string()).default([]),
ivar_count: z.number().int().nonnegative().default(0),
instance_size: z.number().int().nonnegative().nullable(),
});
export type ObjcClass = z.infer<typeof objcClassSchema>;
/** Swift declaration kind. */
export const swiftDeclKindSchema = z.enum([
"class",
"struct",
"enum",
"protocol",
"extension",
"actor",
"global_var",
"global_func",
]);
export type SwiftDeclKind = z.infer<typeof swiftDeclKindSchema>;
/** Swift access level. */
export const swiftAccessLevelSchema = z.enum([
"private",
"fileprivate",
"internal",
"public",
"open",
]);
export type SwiftAccessLevel = z.infer<typeof swiftAccessLevelSchema>;
/** Swift declaration metadata. */
export const swiftDeclSchema = z.strictObject({
kind: swiftDeclKindSchema,
name: z.string().min(1),
module: z.string().nullable(),
access_level: swiftAccessLevelSchema.default("internal"),
super_class: z.string().nullable(),
protocols: z.array(z.string()).default([]),
is_final: z.boolean().default(false),
is_required: z.boolean().default(false),
is_convenience_init: z.boolean().default(false),
is_override: z.boolean().default(false),
});
export type SwiftDecl = z.infer<typeof swiftDeclSchema>;
/** Database save/read operation type. */
export const dbOperationSchema = z.enum([
"save",
"readback",
"open_database",
"close_database",
"export",
"import",
]);
export type DbOperation = z.infer<typeof dbOperationSchema>;
/** Database save operation result. */
export const dbSaveResultSchema = z.strictObject({
operation: dbOperationSchema,
succeeded: z.boolean(),
preserved_names: z.number().int().nonnegative().default(0),
preserved_comments: z.number().int().nonnegative().default(0),
preserved_bookmarks: z.number().int().nonnegative().default(0),
database_path: z.string().nullable(),
error: z.string().nullable(),
});
export type DbSaveResult = z.infer<typeof dbSaveResultSchema>;
/** Result of deeper ObjC/Swift metadata extraction. */
export const objcSwiftMetadataSchema = z.strictObject({
objc_classes: z.array(objcClassSchema).default([]),
objc_protocols: z.array(objcProtocolSchema).default([]),
swift_decls: z.array(swiftDeclSchema).default([]),
db_save_result: dbSaveResultSchema.nullable(),
});
export type ObjcSwiftMetadata = z.infer<typeof objcSwiftMetadataSchema>;
/** Check if a selector name looks like a getter. */
export function isGetterSelector(selector: string): boolean {
return /^[a-z][a-zA-Z0-9_]*$/u.test(selector) && !selector.includes(":");
}
/** Check if a selector name looks like a setter. */
export function isSetterSelector(selector: string): boolean {
return selector.startsWith("set") && selector.endsWith(":");
}
/** Extract property name from a getter/setter selector. */
export function propertyNameFromSelector(selector: string): string | null {
if (isSetterSelector(selector)) {
const inner = selector.slice(3, -1);
return inner.charAt(0).toLowerCase() + inner.slice(1);
}
if (isGetterSelector(selector)) {
return selector;
}
return null;
}
/** Count ObjC methods by type. */
export function countMethodsByType(
methods: readonly ObjcMethod[],
): Record<ObjcMethodType, number> {
return {
instance: methods.filter((m) => m.method_type === "instance").length,
class: methods.filter((m) => m.method_type === "class").length,
ivar_getter: methods.filter((m) => m.method_type === "ivar_getter").length,
ivar_setter: methods.filter((m) => m.method_type === "ivar_setter").length,
};
}
/** Get all Swift declarations of a specific kind. */
export function swiftDeclsByKind(
decls: readonly SwiftDecl[],
kind: SwiftDeclKind,
): SwiftDecl[] {
return decls.filter((d) => d.kind === kind);
}
/** Check if a database save preserved all expected items. */
export function isDbSaveComplete(
result: DbSaveResult,
expectedNames: number,
expectedComments: number,
expectedBookmarks: number,
): boolean {
return (
result.succeeded &&
result.preserved_names >= expectedNames &&
result.preserved_comments >= expectedComments &&
result.preserved_bookmarks >= expectedBookmarks
);
}
+144
View File
@@ -0,0 +1,144 @@
import { z } from "zod";
/** Supported Windows package formats. */
export const packageFormatSchema = z.enum(["msix", "msi", "appx"]);
export type PackageFormat = z.infer<typeof packageFormatSchema>;
/** A resource entry within a package. */
export const packageResourceSchema = z.strictObject({
/** Resource path within the package. */
path: z.string().min(1),
/** Resource type. */
type: z.enum([
"manifest",
"icon",
"configuration",
"certificate",
"executable",
"library",
"data",
"other",
]),
/** Size in bytes. */
size: z.number().int().nonnegative(),
/** SHA-256 digest. */
digest: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.nullable(),
});
export type PackageResource = z.infer<typeof packageResourceSchema>;
/** Digital signature information. */
export const digitalSignatureSchema = z.strictObject({
/** Whether the package is signed. */
is_signed: z.boolean(),
/** Signer subject name. */
signer_subject: z.string().nullable(),
/** Certificate thumbprint. */
certificate_thumbprint: z.string().nullable(),
/** Whether the signature is valid. */
is_valid: z.boolean().default(false),
/** Whether the signature is timestamped. */
is_timestamped: z.boolean().default(false),
/** Timestamp signer if present. */
timestamp_signer: z.string().nullable(),
});
export type DigitalSignature = z.infer<typeof digitalSignatureSchema>;
/** A Windows package manifest for static analysis. */
export const packageManifestSchema = z.strictObject({
/** Package format. */
format: packageFormatSchema,
/** Package identity name. */
name: z.string().min(1),
/** Package publisher. */
publisher: z.string().nullable(),
/** Package version. */
version: z.string().nullable(),
/** Architecture. */
architecture: z.enum(["x86", "x64", "arm", "arm64", "neutral", "unknown"]),
/** Package resources. */
resources: z.array(packageResourceSchema).default([]),
/** Digital signature. */
signature: digitalSignatureSchema,
/** Whether the package is a framework. */
is_framework: z.boolean().default(false),
/** Package dependencies. */
dependencies: z.array(z.string()).default([]),
/** Capabilities declared in the manifest. */
capabilities: z.array(z.string()).default([]),
});
export type PackageManifest = z.infer<typeof packageManifestSchema>;
/** Detect package format from file extension. */
export function detectPackageFormat(path: string): PackageFormat | null {
const lower = path.toLowerCase();
if (lower.endsWith(".msix")) return "msix";
if (lower.endsWith(".msi")) return "msi";
if (lower.endsWith(".appx")) return "appx";
return null;
}
/** Check if a resource path looks like a manifest. */
export function isManifestResource(path: string): boolean {
const lower = path.toLowerCase();
return (
lower.includes("appxmanifest.xml") ||
lower.includes("appxmanifest") ||
lower.includes("manifest.xml") ||
lower.endsWith("_manifest.xml")
);
}
/** Check if a resource path looks like a configuration file. */
export function isConfigurationResource(path: string): boolean {
const lower = path.toLowerCase();
return (
lower.endsWith(".xml") ||
lower.endsWith(".json") ||
lower.endsWith(".ini") ||
lower.endsWith(".config")
);
}
/** Classify a resource by its path. */
export function classifyResource(path: string): PackageResource["type"] {
if (isManifestResource(path)) return "manifest";
const lower = path.toLowerCase();
if (
lower.endsWith(".ico") ||
lower.endsWith(".png") ||
lower.endsWith(".jpg") ||
lower.endsWith(".jpeg")
)
return "icon";
if (isConfigurationResource(path)) return "configuration";
if (
lower.endsWith(".cer") ||
lower.endsWith(".pfx") ||
lower.endsWith(".p12")
)
return "certificate";
if (lower.endsWith(".exe") || lower.endsWith(".dll"))
return lower.endsWith(".exe") ? "executable" : "library";
return "other";
}
/** Get all resources of a specific type. */
export function resourcesByType(
manifest: PackageManifest,
type: PackageResource["type"],
): PackageResource[] {
return manifest.resources.filter((r) => r.type === type);
}
/** Get the total size of all resources. */
export function totalResourceSize(manifest: PackageManifest): number {
return manifest.resources.reduce((sum, r) => sum + r.size, 0);
}
/** Check if a package has a valid signature. */
export function hasValidSignature(manifest: PackageManifest): boolean {
return manifest.signature.is_signed && manifest.signature.is_valid;
}
+225
View File
@@ -0,0 +1,225 @@
import { z } from "zod";
/** PE/COFF section characteristics flags. */
export const sectionCharacteristicsSchema = z.object({
/** Section contains executable code. */
has_code: z.boolean().default(false),
/** Section contains initialized data. */
has_initialized_data: z.boolean().default(false),
/** Section contains uninitialized data. */
has_uninitialized_data: z.boolean().default(false),
/** Section can be read. */
readable: z.boolean().default(false),
/** Section can be written. */
writable: z.boolean().default(false),
/** Section can be executed. */
executable: z.boolean().default(false),
});
/** PE/COFF section header. */
export const peSectionSchema = z.strictObject({
name: z.string().min(1),
virtual_size: z.number().int().nonnegative(),
virtual_address: z.number().int().nonnegative(),
raw_size: z.number().int().nonnegative(),
raw_offset: z.number().int().nonnegative(),
characteristics: sectionCharacteristicsSchema,
});
export type PeSection = z.infer<typeof peSectionSchema>;
/** PE import entry. */
export const peImportSchema = z.strictObject({
dll: z.string().min(1),
function_name: z.string().min(1),
ordinal: z.number().int().nullable(),
is_delay_import: z.boolean().default(false),
});
export type PeImport = z.infer<typeof peImportSchema>;
/** PE export entry. */
export const peExportSchema = z.strictObject({
name: z.string().min(1),
ordinal: z.number().int().nonnegative(),
rva: z.number().int().nonnegative(),
forwarder: z.string().nullable(),
});
export type PeExport = z.infer<typeof peExportSchema>;
/** PE/COFF resource entry. */
export const peResourceSchema = z.strictObject({
type: z.string().min(1),
name: z.string().nullable(),
language: z.number().int().nullable(),
rva: z.number().int().nonnegative(),
size: z.number().int().nonnegative(),
});
export type PeResource = z.infer<typeof peResourceSchema>;
/** PE debug directory entry. */
export const peDebugEntrySchema = z.strictObject({
type: z.string().min(1),
rva: z.number().int().nonnegative(),
size: z.number().int().nonnegative(),
/** PDB GUID if this is a CodeView entry. */
pdb_guid: z.string().nullable(),
/** PDB age if this is a CodeView entry. */
pdb_age: z.number().int().nullable(),
/** PDB path if this is a CodeView entry. */
pdb_path: z.string().nullable(),
});
export type PeDebugEntry = z.infer<typeof peDebugEntrySchema>;
/** TLS callback entry. */
export const peTlsCallbackSchema = z.strictObject({
callback_rva: z.number().int().nonnegative(),
index: z.number().int().nonnegative(),
});
export type PeTlsCallback = z.infer<typeof peTlsCallbackSchema>;
/** Architecture/machine type. */
export const peMachineTypeSchema = z.enum([
"x86",
"x64",
"arm",
"arm64",
"ia64",
"unknown",
]);
export type PeMachineType = z.infer<typeof peMachineTypeSchema>;
/** PE/COFF manifest for static inspection. */
export const peManifestSchema = z.strictObject({
/** DOS header magic. */
dos_magic: z.literal(0x5a4d),
/** PE signature. */
pe_signature: z.literal(0x00004550),
/** Machine type. */
machine: peMachineTypeSchema,
/** Number of sections. */
number_of_sections: z.number().int().positive(),
/** Timestamp from the COFF header. */
timestamp: z.number().int().nullable(),
/** PE characteristics flags. */
is_dll: z.boolean().default(false),
is_executable: z.boolean().default(false),
is_console: z.boolean().default(true),
/** Entry point RVA. */
entry_point: z.number().int().nonnegative(),
/** Image base. */
image_base: z.number().int().nonnegative(),
/** Section alignment. */
section_alignment: z.number().int().positive(),
/** Subsystem version. */
subsystem_version: z.string().nullable(),
/** Sections. */
sections: z.array(peSectionSchema).min(0).max(96),
/** Imports. */
imports: z.array(peImportSchema).default([]),
/** Exports. */
exports: z.array(peExportSchema).default([]),
/** Resources. */
resources: z.array(peResourceSchema).default([]),
/** Debug directory entries. */
debug_entries: z.array(peDebugEntrySchema).default([]),
/** TLS callbacks. */
tls_callbacks: z.array(peTlsCallbackSchema).default([]),
/** Relocations count (not all entries). */
relocations_count: z.number().int().nonnegative().default(0),
/** Image file characteristics. */
image_characteristics: z.array(z.string()).default([]),
});
export type PeManifest = z.infer<typeof peManifestSchema>;
/** Parse machine type from COFF machine field. */
export function parseMachineType(machine: number): PeMachineType {
switch (machine) {
case 0x014c:
return "x86";
case 0x8664:
return "x64";
case 0x01c0:
case 0x01c4:
return "arm";
case 0xaa64:
return "arm64";
case 0x0200:
return "ia64";
default:
return "unknown";
}
}
/** Parse section characteristics flags. */
export function parseSectionCharacteristics(
characteristics: number,
): z.infer<typeof sectionCharacteristicsSchema> {
const IMAGE_SCN_CNT_CODE = 0x00000020;
const IMAGE_SCN_CNT_INITIALIZED_DATA = 0x00000040;
const IMAGE_SCN_CNT_UNINITIALIZED_DATA = 0x00000080;
const IMAGE_SCN_MEM_READ = 0x40000000;
const IMAGE_SCN_MEM_WRITE = 0x80000000;
const IMAGE_SCN_MEM_EXECUTE = 0x20000000;
return {
has_code: (characteristics & IMAGE_SCN_CNT_CODE) !== 0,
has_initialized_data:
(characteristics & IMAGE_SCN_CNT_INITIALIZED_DATA) !== 0,
has_uninitialized_data:
(characteristics & IMAGE_SCN_CNT_UNINITIALIZED_DATA) !== 0,
readable: (characteristics & IMAGE_SCN_MEM_READ) !== 0,
writable: (characteristics & IMAGE_SCN_MEM_WRITE) !== 0,
executable: (characteristics & IMAGE_SCN_MEM_EXECUTE) !== 0,
};
}
/** Parse image characteristics flags. */
export function parseImageCharacteristics(characteristics: number): string[] {
const IMAGE_DLL = 0x2000;
const IMAGE_EXECUTABLE = 0x0002;
const IMAGE_CONSOLE = 0x0003;
const flags: string[] = [];
if (characteristics & IMAGE_DLL) flags.push("DLL");
if (characteristics & IMAGE_EXECUTABLE) flags.push("Executable");
if ((characteristics & 0x0000000f) === IMAGE_CONSOLE) flags.push("Console");
return flags;
}
/** Parse a PE debug directory type. */
export function parseDebugType(type: number): string {
switch (type) {
case 0:
return "UNKNOWN";
case 1:
return "COFF";
case 2:
return "CODEVIEW";
case 3:
return "POGO";
case 4:
return "MISC";
default:
return "UNKNOWN";
}
}
/** Check if a PE manifest has PDB debug info. */
export function hasPdbInfo(manifest: PeManifest): boolean {
return manifest.debug_entries.some(
(e) => e.pdb_guid !== null && e.pdb_path !== null,
);
}
/** Get all imported DLLs from a PE manifest. */
export function getImportedDlls(manifest: PeManifest): string[] {
return [...new Set(manifest.imports.map((i) => i.dll))];
}
/** Get all exported function names from a PE manifest. */
export function getExportedFunctions(manifest: PeManifest): string[] {
return manifest.exports.map((e) => e.name);
}
/** Count executable sections. */
export function countExecutableSections(manifest: PeManifest): number {
return manifest.sections.filter((s) => s.characteristics.executable).length;
}
+272
View File
@@ -0,0 +1,272 @@
import { z } from "zod";
import { jsonValueSchema } from "./jsonValue.js";
/** Supported protocol families for structured protocol capture. */
export const protocolFamilySchema = z.enum([
"grpc",
"protobuf",
"json-rpc",
"messagepack",
]);
export type ProtocolFamily = z.infer<typeof protocolFamilySchema>;
/** A decoded field from a protocol message. */
export const decodedFieldSchema = z.strictObject({
/** Field name or path within the message structure. */
path: z.string().min(1),
/** Wire type or encoding hint. */
wire_type: z.string().nullable(),
/** Decoded field value. */
value: jsonValueSchema.nullable(),
/** Whether this field value was inferred rather than decoded. */
inferred: z.boolean().default(false),
});
export type DecodedField = z.infer<typeof decodedFieldSchema>;
/** Schema inference hypothesis for a repeated message pattern. */
export const schemaHypothesisSchema = z.strictObject({
/** Hypothesized field name. */
field_name: z.string().min(1),
/** Inferred type. */
inferred_type: z.string().min(1),
/** Confidence: 0-1 */
confidence: z.number().min(0).max(1),
/** Supporting evidence count. */
evidence_count: z.number().int().nonnegative(),
});
export type SchemaHypothesis = z.infer<typeof schemaHypothesisSchema>;
/** Result of decoding a single protocol message. */
export const protocolMessageSchema = z.strictObject({
/** Monotonic sequence number. */
sequence: z.number().int().nonnegative(),
/** Timestamp in milliseconds. */
at_ms: z.number().int().nonnegative(),
/** Protocol family. */
family: protocolFamilySchema,
/** Direction of the message. */
direction: z.enum(["request", "response"]),
/** Transport endpoint or path (e.g. gRPC method path). */
endpoint: z.string().nullable(),
/** Content type of the raw payload. */
content_type: z.string().nullable(),
/** Raw payload bytes as base64. */
raw_payload: z.string().nullable(),
/** Decoded fields from the payload. */
decoded_fields: z.array(decodedFieldSchema).default([]),
/** Inferred schema hypotheses. */
schema_hypotheses: z.array(schemaHypothesisSchema).default([]),
/** Whether decoding was truncated. */
truncated: z.boolean().default(false),
/** Whether credentials were detected and redacted. */
credentials_redacted: z.boolean().default(false),
});
export type ProtocolMessage = z.infer<typeof protocolMessageSchema>;
/** A captured protocol session with messages and inferred schemas. */
export const protocolCaptureSchema = z.strictObject({
/** Protocol family for this capture. */
family: protocolFamilySchema,
/** Captured messages in order. */
messages: z.array(protocolMessageSchema).min(0).max(10_000),
/** Aggregated schema hypotheses across all messages. */
inferred_schema: z.array(schemaHypothesisSchema).default([]),
/** Whether any message was truncated. */
has_truncated: z.boolean().default(false),
/** Whether credentials were detected and redacted. */
credentials_detected: z.boolean().default(false),
});
export type ProtocolCapture = z.infer<typeof protocolCaptureSchema>;
/** Classification of a byte sequence as a known protocol family. */
export function classifyProtocolFamily(
contentType: string | null,
path: string | null,
): ProtocolFamily | null {
if (contentType) {
if (contentType.includes("application/grpc")) return "grpc";
if (contentType.includes("application/x-protobuf")) return "protobuf";
if (contentType.includes("application/json-rpc")) return "json-rpc";
if (
contentType.includes("application/msgpack") ||
contentType.includes("application/x-msgpack")
)
return "messagepack";
}
if (path) {
if (path.startsWith("/grpc.") || path.includes("/grpc/")) return "grpc";
if (path.includes("/json-rpc") || path.includes("/jsonrpc"))
return "json-rpc";
}
return null;
}
/** Credential-like field names that should be redacted. */
const CREDENTIAL_PATTERNS = [
"password",
"passwd",
"secret",
"token",
"api_key",
"apikey",
"authorization",
"auth",
"credential",
"private_key",
];
/** Check if a field path looks like it may contain credentials. */
export function looksLikeCredential(path: string): boolean {
const lower = path.toLowerCase();
return CREDENTIAL_PATTERNS.some((p) => lower.includes(p));
}
/** Decode a JSON-RPC message from raw payload bytes. */
export function decodeJsonRpc(rawPayload: Uint8Array): {
decoded_fields: DecodedField[];
truncated: boolean;
} {
const text = new TextDecoder().decode(rawPayload);
const parsed = JSON.parse(text);
const fields: DecodedField[] = [];
if (typeof parsed === "object" && parsed !== null) {
for (const [key, value] of Object.entries(parsed)) {
if (looksLikeCredential(key)) {
fields.push({
path: key,
wire_type: "json",
value: "[REDACTED]",
inferred: false,
});
} else {
fields.push({
path: key,
wire_type: "json",
value: value as never,
inferred: false,
});
}
}
}
return { decoded_fields: fields, truncated: false };
}
/** Decode a MessagePack message (simplified: only checks basic structure). */
export function decodeMessagePack(rawPayload: Uint8Array): {
decoded_fields: DecodedField[];
truncated: boolean;
} {
const fields: DecodedField[] = [];
// MessagePack uses a single-byte type tag
if (rawPayload.length === 0) {
return { decoded_fields: [], truncated: false };
}
const tag = rawPayload[0]!;
// Map type: 0x80-0x8f (fixmap), 0xde (map16), 0xdf (map32)
if ((tag >= 0x80 && tag <= 0x8f) || tag === 0xde || tag === 0xdf) {
fields.push({
path: "type",
wire_type: "msgpack",
value: "map",
inferred: false,
});
}
// Array type: 0x90-0x9f (fixarray), 0xdc (array16), 0xdd (array32)
else if ((tag >= 0x90 && tag <= 0x9f) || tag === 0xdc || tag === 0xdd) {
fields.push({
path: "type",
wire_type: "msgpack",
value: "array",
inferred: false,
});
} else {
fields.push({
path: "type",
wire_type: "msgpack",
value: "unknown",
inferred: true,
});
}
return {
decoded_fields: fields,
truncated: rawPayload.length > 10_000,
};
}
/** Decode a gRPC frame (5-byte header + protobuf payload). */
export function decodeGrpcFrame(rawPayload: Uint8Array): {
decoded_fields: DecodedField[];
truncated: boolean;
} {
// gRPC uses a 5-byte prefix: 1 byte compressed flag + 4 byte length
if (rawPayload.length < 5) {
return {
decoded_fields: [
{
path: "error",
wire_type: "grpc",
value: "frame too short",
inferred: false,
},
],
truncated: false,
};
}
const compressed = rawPayload[0] !== 0;
const length =
(rawPayload[1]! << 24) |
(rawPayload[2]! << 16) |
(rawPayload[3]! << 8) |
rawPayload[4]!;
return {
decoded_fields: [
{
path: "compressed",
wire_type: "grpc",
value: compressed,
inferred: false,
},
{
path: "message_length",
wire_type: "grpc",
value: length,
inferred: false,
},
],
truncated: length > 10_000,
};
}
/** Infer schema hypotheses from a set of decoded messages. */
export function inferMessageSchema(
messages: readonly ProtocolMessage[],
): SchemaHypothesis[] {
const fieldCounts = new Map<string, { count: number; types: Set<string> }>();
for (const msg of messages) {
for (const field of msg.decoded_fields) {
const existing = fieldCounts.get(field.path);
if (existing) {
existing.count++;
if (field.wire_type) existing.types.add(field.wire_type);
} else {
fieldCounts.set(field.path, {
count: 1,
types: new Set(field.wire_type ?? "unknown"),
});
}
}
}
const hypotheses: SchemaHypothesis[] = [];
for (const [field_name, data] of fieldCounts) {
hypotheses.push({
field_name,
inferred_type: [...data.types].join("|"),
confidence: Math.min(1, data.count / messages.length || 0),
evidence_count: data.count,
});
}
return hypotheses;
}
+1 -1
View File
@@ -1,7 +1,7 @@
/** Generated from package.json and package-lock.json; do not edit. */
export const PACKAGE_METADATA = {
name: "rea-agents",
version: "2.6.0", // x-release-please-version
version: "2.7.0", // x-release-please-version
serverSdkVersion: "2.0.0-beta.4",
clientSdkVersion: "2.0.0-beta.4",
coreSdkVersion: "2.0.0-beta.4",
+152
View File
@@ -0,0 +1,152 @@
import { describe, expect, it } from "vitest";
import {
analyzeBytecodeArtifacts,
bytecodeAnalysisSchema,
classifyProvenance,
detectArtifactFormat,
detectBytecodeFamily,
type BytecodeArtifact,
type BytecodeSymbol,
} from "../src/domain/bytecodeProvider.js";
describe("bytecode provider", () => {
it("detects JVM family from extensions", () => {
expect(detectBytecodeFamily("App.class")).toBe("jvm");
expect(detectBytecodeFamily("app.jar")).toBe("jvm");
expect(detectBytecodeFamily("webapp.war")).toBe("jvm");
expect(detectBytecodeFamily("app.ear")).toBe("jvm");
});
it("detects Python family from extensions", () => {
expect(detectBytecodeFamily("module.pyc")).toBe("python");
expect(detectBytecodeFamily("module.pyo")).toBe("python");
expect(detectBytecodeFamily("package.whl")).toBe("python");
expect(detectBytecodeFamily("app.pyz")).toBe("python");
expect(detectBytecodeFamily("app.zipapp")).toBe("python");
});
it("returns null for unknown extensions", () => {
expect(detectBytecodeFamily("readme.txt")).toBeNull();
expect(detectBytecodeFamily("script.js")).toBeNull();
});
it("detects artifact format from path", () => {
expect(detectArtifactFormat("App.class")).toBe("class");
expect(detectArtifactFormat("lib.jar")).toBe("jar");
expect(detectArtifactFormat("web.war")).toBe("war");
expect(detectArtifactFormat("mod.pyc")).toBe("pyc");
expect(detectArtifactFormat("pkg.whl")).toBe("whl");
expect(detectArtifactFormat("unknown.xyz")).toBeNull();
});
it("classifies standard library provenance", () => {
expect(classifyProvenance("/usr/lib/stdlib", "java.lang.String")).toBe(
"standard_library",
);
expect(
classifyProvenance("/lib/python3.10/site-packages/numpy", "__init__"),
).toBe("standard_library");
});
it("classifies generated provenance", () => {
expect(classifyProvenance("/build/generated/src", "GeneratedClass")).toBe(
"generated",
);
expect(
classifyProvenance("/__pycache__/module.cpython-310.pyc", "module"),
).toBe("generated");
});
it("classifies vendored provenance", () => {
expect(classifyProvenance("/vendor/libs/lib.jar", "VendorLib")).toBe(
"vendored",
);
expect(classifyProvenance("/third_party/pkg/module.pyc", "module")).toBe(
"vendored",
);
});
it("classifies application provenance", () => {
expect(classifyProvenance("/src/main/App.java", "com.example.App")).toBe(
"application",
);
expect(classifyProvenance("/src/app.py", "main")).toBe("application");
});
it("analyzes bytecode artifacts and computes summary", () => {
const artifacts: BytecodeArtifact[] = [
{
path: "src/App.class",
family: "jvm",
format: "class",
size: 1000,
digest: "a".repeat(64),
symbols: [
{
name: "com.example.App",
raw_location: "0x1000",
kind: "class",
bytecode_version: 52,
provenance: "application",
is_public: true,
},
{
name: "java.lang.String",
raw_location: "0x2000",
kind: "class",
bytecode_version: 52,
provenance: "standard_library",
is_public: true,
},
],
is_standard_library: false,
is_generated: false,
is_vendored: false,
},
{
path: "lib/generated/Generated.class",
family: "jvm",
format: "class",
size: 500,
digest: "b".repeat(64),
symbols: [
{
name: "GeneratedClass",
raw_location: "0x3000",
kind: "class",
bytecode_version: 52,
provenance: "generated",
is_public: false,
},
],
is_standard_library: false,
is_generated: true,
is_vendored: false,
},
];
const result = analyzeBytecodeArtifacts(artifacts, "jvm");
expect(result.family).toBe("jvm");
expect(result.total_symbols).toBe(3);
expect(result.application_symbols).toBe(1);
expect(result.standard_library_symbols).toBe(1);
expect(result.generated_symbols).toBe(1);
expect(result.vendored_symbols).toBe(0);
// Validate schema
const parsed = bytecodeAnalysisSchema.safeParse(result);
expect(parsed.success).toBe(true);
});
it("uses BytecodeSymbol type", () => {
const sym: BytecodeSymbol = {
name: "com.example.Test",
raw_location: "0x100",
kind: "class",
bytecode_version: 52,
provenance: "application",
is_public: true,
};
expect(sym.provenance).toBe("application");
});
});
+181
View File
@@ -0,0 +1,181 @@
import { describe, expect, it } from "vitest";
import {
CONFORMANCE_PACKAGE_VERSION,
conformancePackageSchema,
computePackageId,
createConformancePackage,
validateConformancePackage,
type ScenarioManifest,
type ReplayPlan,
type ShimPlan,
type ExpectedEvidence,
} from "../src/domain/conformancePackage.js";
const validPackage = createConformancePackage({
schema_version: CONFORMANCE_PACKAGE_VERSION,
name: "test-fixture",
description: "A test conformance fixture",
created_at: "2026-07-28T00:00:00Z",
scenarios: [
{
scenario_id: "s1",
name: "Simple spawn",
description: "A simple process spawn scenario",
fixture_path: "tests/conformance/c/fixture.c",
expected_exit_code: 0,
expected_patterns: ["Hello", "World"],
},
],
replay_plans: [
{
scenario_id: "s1",
steps: [
{
step_id: "step1",
action: "compile",
arguments: ["gcc", "fixture.c"],
timeout_ms: 5000,
},
],
environment: {},
},
],
shim_plans: [],
expected_evidence: [
{
scenario_id: "s1",
envelopes: [],
bundle: null,
required_dimensions: ["exit_code", "stdout"],
},
],
verifier_contracts: [
{
scenario_id: "s1",
dimensions: [
{
name: "exit_code",
required: true,
comparison: "exact",
},
],
timing_tolerance_ms: 100,
},
],
});
describe("conformance package format", () => {
it("validates a well-formed package", () => {
const result = validateConformancePackage(validPackage);
expect(result.ok).toBe(true);
});
it("rejects invalid schema version", () => {
const result = validateConformancePackage({
...validPackage,
schema_version: 999,
});
expect(result.ok).toBe(false);
});
it("rejects duplicate scenario IDs", () => {
const result = validateConformancePackage({
...validPackage,
scenarios: [validPackage.scenarios[0], validPackage.scenarios[0]],
});
expect(result.ok).toBe(false);
});
it("rejects replay plan referencing non-existent scenario", () => {
const result = validateConformancePackage({
...validPackage,
replay_plans: [
{
scenario_id: "nonexistent",
steps: [
{
step_id: "step1",
action: "run",
arguments: [],
timeout_ms: 1000,
},
],
environment: {},
},
],
});
expect(result.ok).toBe(false);
});
it("rejects verifier contract referencing non-existent scenario", () => {
const result = validateConformancePackage({
...validPackage,
verifier_contracts: [
{
scenario_id: "nonexistent",
dimensions: [
{ name: "exit_code", required: true, comparison: "exact" },
],
timing_tolerance_ms: 0,
},
],
});
expect(result.ok).toBe(false);
});
it("rejects expected evidence referencing non-existent scenario", () => {
const result = validateConformancePackage({
...validPackage,
expected_evidence: [
{
scenario_id: "nonexistent",
envelopes: [],
bundle: null,
required_dimensions: [],
},
],
});
expect(result.ok).toBe(false);
});
it("computes a deterministic package ID", () => {
const id = computePackageId({
...validPackage,
});
expect(id).toMatch(/^cp_[a-f0-9]{64}$/u);
// Same input yields same ID
const id2 = computePackageId({
...validPackage,
});
expect(id).toBe(id2);
});
it("produces different IDs for different packages", () => {
const id1 = computePackageId({ ...validPackage, name: "packageA" });
const id2 = computePackageId({ ...validPackage, name: "packageB" });
expect(id1).not.toBe(id2);
});
it("uses all exported types", () => {
const scenario: ScenarioManifest = validPackage.scenarios[0]!;
expect(scenario.scenario_id).toBe("s1");
const replay: ReplayPlan = validPackage.replay_plans[0]!;
expect(replay.scenario_id).toBe("s1");
const shim: ShimPlan = validPackage.shim_plans[0] ?? {
scenario_id: "s1",
shims: [],
};
expect(shim.scenario_id).toBe("s1");
const evidence: ExpectedEvidence = validPackage.expected_evidence[0]!;
expect(evidence.scenario_id).toBe("s1");
});
it("parses via zod schema", () => {
const result = conformancePackageSchema.safeParse(validPackage);
expect(result.success).toBe(true);
});
});
+190
View File
@@ -0,0 +1,190 @@
import { describe, expect, it } from "vitest";
import {
CONFORMANCE_PACKAGE_VERSION,
createConformancePackage,
type ConformancePackage,
} from "../src/domain/conformancePackage.js";
import {
replayConformancePackage,
type ScenarioReplayResult,
} from "../src/domain/conformanceReplay.js";
const validPackage = createConformancePackage({
schema_version: CONFORMANCE_PACKAGE_VERSION,
name: "test-fixture",
description: "A test conformance fixture",
created_at: "2026-07-28T00:00:00Z",
scenarios: [
{
scenario_id: "s1",
name: "Simple spawn",
description: "A simple process spawn scenario",
fixture_path: "tests/conformance/c/fixture.c",
expected_exit_code: 0,
expected_patterns: [],
},
],
replay_plans: [
{
scenario_id: "s1",
steps: [
{
step_id: "step1",
action: "run",
arguments: [],
timeout_ms: 1000,
},
],
environment: {},
},
],
shim_plans: [],
expected_evidence: [
{
scenario_id: "s1",
envelopes: [],
bundle: null,
required_dimensions: [],
},
],
verifier_contracts: [
{
scenario_id: "s1",
dimensions: [{ name: "exit_code", required: true, comparison: "exact" }],
timing_tolerance_ms: 0,
},
],
});
async function passingRunner(
scenarioId: string,
): Promise<ScenarioReplayResult> {
return {
scenario_id: scenarioId,
status: "pass",
exit_code: 0,
duration_ms: 10,
output: "ok",
error: null,
};
}
async function failingRunner(
scenarioId: string,
): Promise<ScenarioReplayResult> {
return {
scenario_id: scenarioId,
status: "fail",
exit_code: 1,
duration_ms: 10,
output: "fail",
error: null,
};
}
describe("conformance CI replay", () => {
it("replays a package with passing scenarios", async () => {
const result = await replayConformancePackage(
validPackage,
{},
passingRunner,
);
expect(result.total_scenarios).toBe(1);
expect(result.passed).toBe(1);
expect(result.failed).toBe(0);
expect(result.errored).toBe(0);
});
it("replays a package with failing scenarios", async () => {
const result = await replayConformancePackage(
validPackage,
{},
failingRunner,
);
expect(result.failed).toBe(1);
expect(result.passed).toBe(0);
});
it("does not detect drift when expected and actual match", async () => {
const result = await replayConformancePackage(
validPackage,
{},
passingRunner,
);
expect(result.drift_detected).toBe(false);
});
it("throws on invalid package", async () => {
await expect(replayConformancePackage({}, {})).rejects.toThrow(
/invalid conformance package/u,
);
});
it("counts all result types", async () => {
const base: ConformancePackage = validPackage;
const multiPackage = createConformancePackage({
...base,
scenarios: [
base.scenarios[0]!,
{
scenario_id: "s2",
name: "Second scenario",
description: "Second",
fixture_path: "tests/conformance/c/fixture2.c",
expected_exit_code: 1,
expected_patterns: [],
},
],
replay_plans: [
base.replay_plans[0]!,
{
scenario_id: "s2",
steps: [
{
step_id: "step1",
action: "run",
arguments: [],
timeout_ms: 1000,
},
],
environment: {},
},
],
expected_evidence: [
base.expected_evidence[0]!,
{
scenario_id: "s2",
envelopes: [],
bundle: null,
required_dimensions: [],
},
],
verifier_contracts: [
base.verifier_contracts[0]!,
{
scenario_id: "s2",
dimensions: [
{ name: "exit_code", required: true, comparison: "exact" },
],
timing_tolerance_ms: 0,
},
],
});
const result = await replayConformancePackage(
multiPackage,
{},
async (scenarioId) => ({
scenario_id: scenarioId,
status: scenarioId === "s1" ? "pass" : "fail",
exit_code: scenarioId === "s1" ? 0 : 1,
duration_ms: 10,
output: "",
error: null,
}),
);
expect(result.total_scenarios).toBe(2);
expect(result.passed).toBe(1);
expect(result.failed).toBe(1);
});
});
+113
View File
@@ -0,0 +1,113 @@
import { describe, expect, it } from "vitest";
import type { VerifierContract } from "../src/domain/conformancePackage.js";
import {
compareDimension,
evaluateTrustGate,
isSemanticDimension,
isVolatileDimension,
} from "../src/domain/conformanceTrustGate.js";
const contract: VerifierContract = {
scenario_id: "s1",
dimensions: [
{ name: "exit_code", required: true, comparison: "exact" },
{ name: "stdout", required: true, comparison: "semantic" },
{ name: "timing", required: true, comparison: "fuzzy" },
],
timing_tolerance_ms: 100,
};
describe("conformance trust gates", () => {
it("classifies volatile dimensions correctly", () => {
expect(isVolatileDimension("timing")).toBe(true);
expect(isVolatileDimension("timestamp")).toBe(true);
expect(isVolatileDimension("pid")).toBe(true);
expect(isVolatileDimension("exit_code")).toBe(false);
});
it("classifies semantic dimensions correctly", () => {
expect(isSemanticDimension("exit_code")).toBe(true);
expect(isSemanticDimension("stdout")).toBe(true);
expect(isSemanticDimension("timing")).toBe(false);
});
it("matches identical values", () => {
const result = compareDimension("exit_code", 0, 0);
expect(result.status).toBe("match");
});
it("detects mismatches", () => {
const result = compareDimension("exit_code", 0, 1);
expect(result.status).toBe("mismatch");
});
it("ignores volatile dimensions", () => {
const result = compareDimension("timing", 100, 200);
expect(result.status).toBe("match");
expect(result.message).toContain("volatile");
});
it("handles truncated evidence", () => {
const result = compareDimension("exit_code", 0, null, {
truncated: true,
});
expect(result.status).toBe("truncated");
});
it("handles undefined values", () => {
const result = compareDimension("exit_code", undefined, undefined);
expect(result.status).toBe("unknown");
});
it("handles missing actual", () => {
const result = compareDimension("exit_code", 0, undefined);
expect(result.status).toBe("mismatch");
});
it("passes when all dimensions match", () => {
const result = evaluateTrustGate(
contract,
{ exit_code: 0, stdout: "hello" },
{ exit_code: 0, stdout: "hello" },
);
expect(result.verdict).toBe("pass");
});
it("fails when a required dimension mismatches", () => {
const result = evaluateTrustGate(
contract,
{ exit_code: 0, stdout: "hello" },
{ exit_code: 1, stdout: "hello" },
);
expect(result.verdict).toBe("fail");
expect(result.first_divergence).not.toBeNull();
expect(result.first_divergence!.dimension).toBe("exit_code");
});
it("reports unknown when both dimensions are undefined", () => {
const result = evaluateTrustGate(contract, {}, {});
// exit_code and stdout are both undefined -> unknown
// timing is volatile -> match
expect(result.verdict).toBe("unknown");
});
it("ignores volatile dimension differences", () => {
const result = evaluateTrustGate(
contract,
{ exit_code: 0, stdout: "hello", timing: 100 },
{ exit_code: 0, stdout: "hello", timing: 200 },
);
expect(result.verdict).toBe("pass");
});
it("truncated evidence is not treated as equivalence", () => {
const result = evaluateTrustGate(
contract,
{ exit_code: 0, stdout: "hello" },
{ exit_code: 0, stdout: "hello" },
{ truncated: true },
);
expect(result.verdict).toBe("fail");
});
});
+157
View File
@@ -0,0 +1,157 @@
import { describe, expect, it } from "vitest";
import {
authEventsByProtocol,
authFlowDuration,
customProtocolCaptureSchema,
correlateProcessIdentity,
failedAuthEvents,
framesByTransport,
looksLikeCredentialFrame,
successfulAuthEvents,
type AuthFlowEvent,
type FrameDirection,
type AuthStage,
type TokenLifecycleEvent,
type CustomProtocolCapture,
type ProtocolFrame,
} from "../src/domain/customProtocolCapture.js";
const sampleFrames: ProtocolFrame[] = [
{
sequence: 0,
at_ms: 100,
transport: "tcp",
direction: "sent",
source_pid: 100,
dest_pid: 200,
source_endpoint: "127.0.0.1:8080",
dest_endpoint: "127.0.0.1:9090",
raw_data: "hello",
decoded_content: "hello",
size: 5,
truncated: false,
},
{
sequence: 1,
at_ms: 200,
transport: "udp",
direction: "received",
source_pid: 200,
dest_pid: 100,
source_endpoint: "127.0.0.1:9090",
dest_endpoint: "127.0.0.1:8080",
raw_data: "world",
decoded_content: "world",
size: 5,
truncated: false,
},
];
const sampleAuthEvents: AuthFlowEvent[] = [
{
sequence: 0,
at_ms: 100,
stage: "init",
protocol: "OAuth2",
token_type: "Bearer",
token_lifecycle: "issued",
correlation_id: "abc-123",
credentials_redacted: true,
succeeded: false,
error: null,
},
{
sequence: 1,
at_ms: 500,
stage: "success",
protocol: "OAuth2",
token_type: "Bearer",
token_lifecycle: "issued",
correlation_id: "abc-123",
credentials_redacted: true,
succeeded: true,
error: null,
},
];
describe("custom protocol capture", () => {
it("validates a well-formed capture", () => {
const capture = {
transport: "tcp" as const,
frames: sampleFrames,
auth_events: sampleAuthEvents,
has_truncated: false,
credentials_detected: false,
};
const result = customProtocolCaptureSchema.safeParse(capture);
expect(result.success).toBe(true);
});
it("correlates process identity", () => {
expect(correlateProcessIdentity(sampleFrames[0]!, 100)).toBe(true);
expect(correlateProcessIdentity(sampleFrames[0]!, 200)).toBe(true);
expect(correlateProcessIdentity(sampleFrames[0]!, 999)).toBe(false);
});
it("filters frames by transport", () => {
const tcpFrames = framesByTransport(sampleFrames, "tcp");
expect(tcpFrames).toHaveLength(1);
const udpFrames = framesByTransport(sampleFrames, "udp");
expect(udpFrames).toHaveLength(1);
});
it("detects credential-like frames", () => {
const credFrame: ProtocolFrame = {
...sampleFrames[0]!,
decoded_content: { password: "secret" },
};
expect(looksLikeCredentialFrame(credFrame)).toBe(true);
expect(looksLikeCredentialFrame(sampleFrames[0]!)).toBe(false);
});
it("filters auth events by protocol", () => {
const oauthEvents = authEventsByProtocol(sampleAuthEvents, "OAuth2");
expect(oauthEvents).toHaveLength(2);
const otherEvents = authEventsByProtocol(sampleAuthEvents, "SAML");
expect(otherEvents).toHaveLength(0);
});
it("gets successful auth events", () => {
const success = successfulAuthEvents(sampleAuthEvents);
expect(success).toHaveLength(1);
expect(success[0]!.succeeded).toBe(true);
});
it("gets failed auth events", () => {
const failed = failedAuthEvents(sampleAuthEvents);
expect(failed).toHaveLength(1);
expect(failed[0]!.succeeded).toBe(false);
});
it("computes auth flow duration", () => {
const duration = authFlowDuration(sampleAuthEvents);
expect(duration).toBe(400);
});
it("returns null for empty auth events", () => {
expect(authFlowDuration([])).toBeNull();
});
it("uses all exported types", () => {
const dir: FrameDirection = "sent";
expect(dir).toBe("sent");
const stage: AuthStage = "init";
expect(stage).toBe("init");
const event: TokenLifecycleEvent = "issued";
expect(event).toBe("issued");
const capture: CustomProtocolCapture = {
transport: "tcp",
frames: sampleFrames,
auth_events: sampleAuthEvents,
has_truncated: false,
credentials_detected: false,
};
expect(capture.transport).toBe("tcp");
});
});
+418
View File
@@ -0,0 +1,418 @@
import { describe, expect, it } from "vitest";
import {
containsProcess,
getDescendants,
maxTreeDepth,
reconstructProcessTree,
type ProcessTreeEvent,
type ProcessEventType,
type ProcessNode,
type ProcessTreeReconstruction,
} from "../src/domain/eventProcessTree.js";
describe("event-backed process tree capture", () => {
it("reconstructs a simple process tree", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 1,
at_ms: 10,
type: "spawn",
pid: 2,
ppid: 1,
process_name: "child",
executable: "/child",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 2,
at_ms: 20,
type: "exit",
pid: 2,
ppid: 1,
process_name: "child",
executable: null,
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: 0,
signal: null,
tid: null,
},
{
sequence: 3,
at_ms: 30,
type: "exit",
pid: 1,
ppid: 0,
process_name: "root",
executable: null,
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: 0,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(result.processes).toHaveLength(2);
expect(result.events_consumed).toBe(4);
expect(result.events_unmatched).toBe(0);
expect(result.short_lived_descendants).toBe(2);
});
it("detects short-lived descendants", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 1,
at_ms: 10,
type: "spawn",
pid: 2,
ppid: 1,
process_name: "short",
executable: "/short",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 2,
at_ms: 11,
type: "exit",
pid: 2,
ppid: 1,
process_name: "short",
executable: null,
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: 0,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(result.short_lived_descendants).toBe(1);
});
it("detects re-exec", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 1,
at_ms: 10,
type: "re_exec",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/newroot",
arguments: ["--new"],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(result.has_re_exec).toBe(true);
const root = result.processes.find((p) => p.pid === 1)!;
expect(root.is_re_exec).toBe(true);
expect(root.executable).toBe("/newroot");
});
it("detects reparenting", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 1,
at_ms: 10,
type: "spawn",
pid: 2,
ppid: 1,
process_name: "child",
executable: "/child",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 2,
at_ms: 20,
type: "reparent",
pid: 2,
ppid: 0,
process_name: "child",
executable: null,
arguments: [],
previous_pid: null,
previous_ppid: 1,
exit_code: null,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(result.has_reparenting).toBe(true);
const child = result.processes.find((p) => p.pid === 2)!;
expect(child.is_reparented).toBe(true);
expect(child.previous_ppid).toBe(1);
expect(child.ppid).toBe(0);
});
it("reports unmatched events for unknown exits", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "exit",
pid: 999,
ppid: null,
process_name: null,
executable: null,
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: 1,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(result.events_unmatched).toBe(1);
expect(result.processes).toHaveLength(0);
});
it("gets descendants", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 1,
at_ms: 10,
type: "spawn",
pid: 2,
ppid: 1,
process_name: "child1",
executable: "/c1",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 2,
at_ms: 20,
type: "spawn",
pid: 3,
ppid: 2,
process_name: "grandchild",
executable: "/gc",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
const descendants = getDescendants(result.processes, 1);
expect(descendants).toHaveLength(2);
expect(descendants).toContain(2);
expect(descendants).toContain(3);
});
it("checks process containment", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(containsProcess(result.processes, 1)).toBe(true);
expect(containsProcess(result.processes, 999)).toBe(false);
});
it("computes max tree depth", () => {
const events: ProcessTreeEvent[] = [
{
sequence: 0,
at_ms: 0,
type: "spawn",
pid: 1,
ppid: 0,
process_name: "root",
executable: "/root",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 1,
at_ms: 10,
type: "spawn",
pid: 2,
ppid: 1,
process_name: "child",
executable: "/c",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
{
sequence: 2,
at_ms: 20,
type: "spawn",
pid: 3,
ppid: 2,
process_name: "gc",
executable: "/gc",
arguments: [],
previous_pid: null,
previous_ppid: null,
exit_code: null,
signal: null,
tid: null,
},
];
const result = reconstructProcessTree(events, 1);
expect(maxTreeDepth(result.processes, 1)).toBe(2);
});
it("uses exported types", () => {
const node: ProcessNode = {
pid: 1,
ppid: null,
process_name: "test",
executable: "/test",
arguments: [],
children: [],
spawn_time_ms: 0,
exit_time_ms: null,
exit_code: null,
is_re_exec: false,
is_reparented: false,
previous_ppid: null,
};
expect(node.pid).toBe(1);
const recon: ProcessTreeReconstruction = {
root_pid: 1,
processes: [node],
events_consumed: 1,
events_unmatched: 0,
short_lived_descendants: 0,
has_re_exec: false,
has_reparenting: false,
};
expect(recon.root_pid).toBe(1);
});
it("uses ProcessEventType", () => {
const t: ProcessEventType = "spawn";
expect(t).toBe("spawn");
});
});
@@ -0,0 +1,129 @@
import { describe, expect, it } from "vitest";
import {
classifyMobileResource,
detectMobileFormat,
detectPlatform,
getAllArchitectures,
hasInternetPermission,
mobileArtifactManifestSchema,
nativeLibsByArchitecture,
type MobileArtifactManifest,
type AndroidManifest,
type IosManifest,
type SigningInfo,
type NativeLibrary,
type MobileResource,
} from "../src/domain/mobileApplicationInvestigation.js";
describe("mobile application investigation", () => {
it("detects mobile format from extension", () => {
expect(detectMobileFormat("app.apk")).toBe("apk");
expect(detectMobileFormat("app.aab")).toBe("aab");
expect(detectMobileFormat("app.ipa")).toBe("ipa");
expect(detectMobileFormat("classes.dex")).toBe("dex");
expect(detectMobileFormat("lib.so")).toBe("native_lib");
expect(detectMobileFormat("readme.txt")).toBeNull();
});
it("detects platform from format", () => {
expect(detectPlatform("apk")).toBe("android");
expect(detectPlatform("aab")).toBe("android");
expect(detectPlatform("dex")).toBe("android");
expect(detectPlatform("ipa")).toBe("ios");
expect(detectPlatform("native_lib")).toBe("cross_platform");
});
it("classifies resources by path", () => {
expect(classifyMobileResource("res/layout/main.xml")).toBe("layout");
expect(classifyMobileResource("res/drawable/icon.png")).toBe("drawable");
expect(classifyMobileResource("assets/data.json")).toBe("asset");
expect(classifyMobileResource("AndroidManifest.xml")).toBe("manifest");
expect(classifyMobileResource("app.entitlements")).toBe("entitlements");
expect(classifyMobileResource("lib/arm64-v8a/libnative.so")).toBe(
"native_lib",
);
expect(classifyMobileResource("unknown.xyz")).toBe("other");
});
const androidManifest: AndroidManifest = {
package_name: "com.example.app",
version_name: "1.0.0",
version_code: 1,
min_sdk: 21,
target_sdk: 34,
permissions: ["android.permission.INTERNET", "android.permission.CAMERA"],
activities: ["MainActivity"],
services: ["BackgroundService"],
receivers: [],
providers: [],
};
const signing: SigningInfo = {
is_signed: true,
signer_identity: "CN=TestSigner",
certificate_fingerprint: "abc123",
signature_scheme: "v2",
is_debuggable: false,
};
const nativeLibs: NativeLibrary[] = [
{
path: "lib/arm64-v8a/libnative.so",
architecture: "arm64-v8a",
size: 100000,
digest: "a".repeat(64),
},
{
path: "lib/armeabi-v7a/libnative.so",
architecture: "armeabi-v7a",
size: 90000,
digest: "b".repeat(64),
},
];
const resources: MobileResource[] = [
{ path: "res/layout/main.xml", type: "layout", size: 1000 },
{ path: "res/drawable/icon.png", type: "drawable", size: 5000 },
];
const validManifest: MobileArtifactManifest = {
format: "apk",
platform: "android",
app_name: "TestApp",
android_manifest: androidManifest,
ios_manifest: null,
signing,
resources,
native_libraries: nativeLibs,
total_size: 5000000,
architectures: ["arm64-v8a", "armeabi-v7a"],
};
it("validates a well-formed manifest", () => {
const result = mobileArtifactManifestSchema.safeParse(validManifest);
expect(result.success).toBe(true);
});
it("filters native libs by architecture", () => {
const arm64 = nativeLibsByArchitecture(validManifest, "arm64-v8a");
expect(arm64).toHaveLength(1);
expect(arm64[0]!.architecture).toBe("arm64-v8a");
});
it("checks internet permission", () => {
expect(hasInternetPermission(validManifest)).toBe(true);
const noInternet: MobileArtifactManifest = {
...validManifest,
android_manifest: { ...androidManifest, permissions: [] },
};
expect(hasInternetPermission(noInternet)).toBe(false);
});
it("gets all architectures", () => {
const archs = getAllArchitectures(validManifest);
expect(archs).toHaveLength(2);
expect(archs).toContain("arm64-v8a");
expect(archs).toContain("armeabi-v7a");
});
});
+130
View File
@@ -0,0 +1,130 @@
import { describe, expect, it } from "vitest";
import {
countMethodsByType,
isDbSaveComplete,
isGetterSelector,
isSetterSelector,
objcSwiftMetadataSchema,
propertyNameFromSelector,
swiftDeclsByKind,
type ObjcClass,
type ObjcMethod,
type ObjcProperty,
type DbOperation,
type ObjcSwiftMetadata,
type ObjcProtocol,
type ObjcPropertyAttribute,
type SwiftDecl,
type SwiftAccessLevel,
type DbSaveResult,
} from "../src/domain/objcSwiftMetadata.js";
describe("ObjC/Swift metadata", () => {
it("identifies getter selectors", () => {
expect(isGetterSelector("name")).toBe(true);
expect(isGetterSelector("setName:")).toBe(false);
expect(isGetterSelector("set")).toBe(true);
});
it("identifies setter selectors", () => {
expect(isSetterSelector("setName:")).toBe(true);
expect(isSetterSelector("name")).toBe(false);
});
it("extracts property name from selector", () => {
expect(propertyNameFromSelector("name")).toBe("name");
expect(propertyNameFromSelector("setName:")).toBe("name");
expect(propertyNameFromSelector("set")).toBe("set");
});
it("counts methods by type", () => {
const methods: ObjcMethod[] = [
{
selector: "init",
method_type: "instance",
address: 0x1000,
is_required: false,
is_optional: false,
},
{
selector: "alloc",
method_type: "class",
address: 0x2000,
is_required: false,
is_optional: false,
},
];
const counts = countMethodsByType(methods);
expect(counts.instance).toBe(1);
expect(counts.class).toBe(1);
expect(counts.ivar_getter).toBe(0);
expect(counts.ivar_setter).toBe(0);
});
it("filters Swift declarations by kind", () => {
const decls: SwiftDecl[] = [
{
kind: "class",
name: "Foo",
module: null,
access_level: "public",
super_class: null,
protocols: [],
is_final: false,
is_required: false,
is_convenience_init: false,
is_override: false,
},
];
const classes = swiftDeclsByKind(decls, "class");
expect(classes).toHaveLength(1);
expect(classes[0]!.name).toBe("Foo");
});
it("checks database save completeness", () => {
const result: DbSaveResult = {
operation: "save",
succeeded: true,
preserved_names: 10,
preserved_comments: 5,
preserved_bookmarks: 3,
database_path: "/tmp/db.hop",
error: null,
};
expect(isDbSaveComplete(result, 10, 5, 3)).toBe(true);
expect(isDbSaveComplete(result, 11, 5, 3)).toBe(false);
});
it("validates a well-formed metadata result", () => {
const meta = {
objc_classes: [] as ObjcClass[],
objc_protocols: [] as ObjcProtocol[],
swift_decls: [] as SwiftDecl[],
db_save_result: null,
};
const result = objcSwiftMetadataSchema.safeParse(meta);
expect(result.success).toBe(true);
});
it("uses all exported types", () => {
const prop: ObjcProperty = {
name: "title",
type_encoding: 'T@"NSString"&,N,V_title',
attributes: [] as ObjcPropertyAttribute[],
is_readonly: false,
getter: "title",
setter: "setTitle:",
};
expect(prop.name).toBe("title");
const op: DbOperation = "save";
expect(op).toBe("save");
const meta: ObjcSwiftMetadata = {
objc_classes: [],
objc_protocols: [],
swift_decls: [],
db_save_result: null,
};
expect(meta.objc_classes).toHaveLength(0);
});
});
+107
View File
@@ -0,0 +1,107 @@
import { describe, expect, it } from "vitest";
import {
classifyResource,
detectPackageFormat,
hasValidSignature,
isConfigurationResource,
isManifestResource,
packageManifestSchema,
resourcesByType,
totalResourceSize,
type PackageManifest,
type DigitalSignature,
} from "../src/domain/packageAnalysis.js";
describe("package analysis", () => {
it("detects package format from extension", () => {
expect(detectPackageFormat("app.msix")).toBe("msix");
expect(detectPackageFormat("installer.msi")).toBe("msi");
expect(detectPackageFormat("app.appx")).toBe("appx");
expect(detectPackageFormat("app.zip")).toBeNull();
});
it("identifies manifest resources", () => {
expect(isManifestResource("AppXManifest.xml")).toBe(true);
expect(isManifestResource("resources.pri")).toBe(false);
});
it("identifies configuration resources", () => {
expect(isConfigurationResource("settings.xml")).toBe(true);
expect(isConfigurationResource("config.json")).toBe(true);
expect(isConfigurationResource("app.exe")).toBe(false);
});
it("classifies resources by path", () => {
expect(classifyResource("AppXManifest.xml")).toBe("manifest");
expect(classifyResource("icon.png")).toBe("icon");
expect(classifyResource("settings.xml")).toBe("configuration");
expect(classifyResource("cert.cer")).toBe("certificate");
expect(classifyResource("app.exe")).toBe("executable");
expect(classifyResource("lib.dll")).toBe("library");
expect(classifyResource("data.bin")).toBe("other");
});
const validManifest: PackageManifest = {
format: "msix",
name: "TestApp",
publisher: "CN=TestPublisher",
version: "1.0.0.0",
architecture: "x64",
resources: [
{
path: "AppXManifest.xml",
type: "manifest",
size: 1000,
digest: "a".repeat(64),
},
{ path: "icon.png", type: "icon", size: 5000, digest: "b".repeat(64) },
{
path: "app.exe",
type: "executable",
size: 50000,
digest: "c".repeat(64),
},
],
signature: {
is_signed: true,
signer_subject: "CN=TestPublisher",
certificate_thumbprint: "abc123",
is_valid: true,
is_timestamped: true,
timestamp_signer: "CN=Timestamp",
},
is_framework: false,
dependencies: ["Microsoft.VCLibs.14.00"],
capabilities: ["internetClient", "localNetwork"],
};
it("validates a well-formed manifest", () => {
const result = packageManifestSchema.safeParse(validManifest);
expect(result.success).toBe(true);
});
it("filters resources by type", () => {
const icons = resourcesByType(validManifest, "icon");
expect(icons).toHaveLength(1);
expect(icons[0]!.path).toBe("icon.png");
});
it("computes total resource size", () => {
expect(totalResourceSize(validManifest)).toBe(56000);
});
it("checks valid signature", () => {
expect(hasValidSignature(validManifest)).toBe(true);
const unsigned: PackageManifest = {
...validManifest,
signature: { ...validManifest.signature, is_valid: false },
};
expect(hasValidSignature(unsigned)).toBe(false);
});
it("uses DigitalSignature type", () => {
const sig: DigitalSignature = validManifest.signature;
expect(sig.is_signed).toBe(true);
});
});
+214
View File
@@ -0,0 +1,214 @@
import { describe, expect, it } from "vitest";
import {
countExecutableSections,
getExportedFunctions,
getImportedDlls,
hasPdbInfo,
parseDebugType,
parseImageCharacteristics,
parseMachineType,
parseSectionCharacteristics,
peManifestSchema,
type PeManifest,
type PeSection,
type PeImport,
type PeExport,
type PeResource,
type PeDebugEntry,
type PeTlsCallback,
} from "../src/domain/peInspection.js";
const validManifest: PeManifest = {
dos_magic: 0x5a4d,
pe_signature: 0x00004550,
machine: "x64",
number_of_sections: 3,
timestamp: 0x12345678,
is_dll: false,
is_executable: true,
is_console: true,
entry_point: 0x1000,
image_base: 0x400000,
section_alignment: 0x1000,
subsystem_version: "10.0",
sections: [
{
name: ".text",
virtual_size: 0x1000,
virtual_address: 0x1000,
raw_size: 0x1000,
raw_offset: 0x400,
characteristics: {
has_code: true,
has_initialized_data: false,
has_uninitialized_data: false,
readable: true,
writable: false,
executable: true,
},
},
{
name: ".data",
virtual_size: 0x500,
virtual_address: 0x2000,
raw_size: 0x500,
raw_offset: 0x1400,
characteristics: {
has_code: false,
has_initialized_data: true,
has_uninitialized_data: false,
readable: true,
writable: true,
executable: false,
},
},
{
name: ".rdata",
virtual_size: 0x200,
virtual_address: 0x3000,
raw_size: 0x200,
raw_offset: 0x1900,
characteristics: {
has_code: false,
has_initialized_data: true,
has_uninitialized_data: false,
readable: true,
writable: false,
executable: false,
},
},
],
imports: [
{
dll: "KERNEL32.DLL",
function_name: "CreateFileW",
ordinal: null,
is_delay_import: false,
},
{
dll: "KERNEL32.DLL",
function_name: "WriteFile",
ordinal: null,
is_delay_import: false,
},
{
dll: "USER32.DLL",
function_name: "MessageBoxW",
ordinal: 100,
is_delay_import: false,
},
],
exports: [
{ name: "DllMain", ordinal: 1, rva: 0x1000, forwarder: null },
{ name: "MyFunction", ordinal: 2, rva: 0x1050, forwarder: null },
],
resources: [
{ type: "RT_VERSION", name: "1", language: 0x0409, rva: 0x4000, size: 100 },
],
debug_entries: [
{
type: "CODEVIEW",
rva: 0x5000,
size: 100,
pdb_guid: "AABBCCDD-EEFF-GGHH-IIJJ-KKLLMMNNOOPP",
pdb_age: 1,
pdb_path: "C:\\src\\app.pdb",
},
],
tls_callbacks: [{ callback_rva: 0x6000, index: 0 }],
relocations_count: 50,
image_characteristics: ["Executable", "Console"],
};
describe("PE/COFF static inspection", () => {
it("parses machine types", () => {
expect(parseMachineType(0x014c)).toBe("x86");
expect(parseMachineType(0x8664)).toBe("x64");
expect(parseMachineType(0x01c0)).toBe("arm");
expect(parseMachineType(0xaa64)).toBe("arm64");
expect(parseMachineType(0x0200)).toBe("ia64");
expect(parseMachineType(0xffff)).toBe("unknown");
});
it("parses section characteristics", () => {
const CODE = 0x00000020;
const READ = 0x40000000;
const EXECUTE = 0x20000000;
const result = parseSectionCharacteristics(CODE | READ | EXECUTE);
expect(result.has_code).toBe(true);
expect(result.readable).toBe(true);
expect(result.executable).toBe(true);
expect(result.writable).toBe(false);
});
it("parses image characteristics", () => {
const DLL = 0x2000;
const EXEC = 0x0002;
const flags = parseImageCharacteristics(DLL | EXEC);
expect(flags).toContain("DLL");
expect(flags).toContain("Executable");
});
it("parses debug types", () => {
expect(parseDebugType(2)).toBe("CODEVIEW");
expect(parseDebugType(1)).toBe("COFF");
expect(parseDebugType(99)).toBe("UNKNOWN");
});
it("validates a well-formed manifest", () => {
const result = peManifestSchema.safeParse(validManifest);
expect(result.success).toBe(true);
});
it("detects PDB info", () => {
expect(hasPdbInfo(validManifest)).toBe(true);
const withoutPdb: PeManifest = {
...validManifest,
debug_entries: [
{
type: "COFF",
rva: 0x5000,
size: 100,
pdb_guid: null,
pdb_age: null,
pdb_path: null,
},
],
};
expect(hasPdbInfo(withoutPdb)).toBe(false);
});
it("gets imported DLLs", () => {
const dlls = getImportedDlls(validManifest);
expect(dlls).toHaveLength(2);
expect(dlls).toContain("KERNEL32.DLL");
expect(dlls).toContain("USER32.DLL");
});
it("gets exported functions", () => {
const exports = getExportedFunctions(validManifest);
expect(exports).toHaveLength(2);
expect(exports).toContain("DllMain");
expect(exports).toContain("MyFunction");
});
it("counts executable sections", () => {
expect(countExecutableSections(validManifest)).toBe(1);
});
it("uses all exported types", () => {
const section: PeSection = validManifest.sections[0]!;
expect(section.name).toBe(".text");
const imp: PeImport = validManifest.imports[0]!;
expect(imp.dll).toBe("KERNEL32.DLL");
const exp: PeExport = validManifest.exports[0]!;
expect(exp.name).toBe("DllMain");
const res: PeResource = validManifest.resources[0]!;
expect(res.type).toBe("RT_VERSION");
const dbg: PeDebugEntry = validManifest.debug_entries[0]!;
expect(dbg.type).toBe("CODEVIEW");
const tls: PeTlsCallback = validManifest.tls_callbacks[0]!;
expect(tls.index).toBe(0);
});
});
+17
View File
@@ -44,6 +44,7 @@ import {
cliCommandDescriptionIssues,
cliCommandOptionNames,
createProductCatalog,
providerCatalogDigest,
serializeProductCatalog,
} from "../scripts/lib/product-catalog.mjs";
@@ -139,6 +140,9 @@ describe("canonical product catalog", () => {
"project_managed_application_graph",
"verify_managed_native_boundaries",
]);
expect(catalog.runtime_catalog.digests.providers_sha256).toBe(
providerCatalogDigest(catalog.providers),
);
expect(
z.toJSONSchema(analysisSnapshotSchema).properties?.snapshot_version,
).toMatchObject({
@@ -230,6 +234,19 @@ describe("canonical product catalog", () => {
);
});
it("changes the provider projection digest when provider facts drift", async () => {
const catalog = await createProductCatalog(root);
const firstProvider = catalog.providers[0];
if (firstProvider === undefined) throw new TypeError("Missing provider");
const driftedProviders = [
{ ...firstProvider, name: `${firstProvider.name} drifted` },
...catalog.providers.slice(1),
];
expect(providerCatalogDigest(driftedProviders)).not.toBe(
catalog.runtime_catalog.digests.providers_sha256,
);
});
it("fails check mode without rewriting a stale generated artifact", async () => {
const directory = await createTestTempDirectory("rea-generated-check-");
temporaryRoots.push(directory);
+207
View File
@@ -0,0 +1,207 @@
import { describe, expect, it } from "vitest";
import {
classifyProtocolFamily,
decodeGrpcFrame,
decodeJsonRpc,
decodeMessagePack,
inferMessageSchema,
looksLikeCredential,
protocolCaptureSchema,
type ProtocolMessage,
type ProtocolCapture,
} from "../src/domain/protocolCapture.js";
describe("protocol capture", () => {
it("classifies gRPC from content type", () => {
expect(classifyProtocolFamily("application/grpc+proto", null)).toBe("grpc");
});
it("classifies protobuf from content type", () => {
expect(classifyProtocolFamily("application/x-protobuf", null)).toBe(
"protobuf",
);
});
it("classifies json-rpc from content type", () => {
expect(classifyProtocolFamily("application/json-rpc", null)).toBe(
"json-rpc",
);
});
it("classifies msgpack from content type", () => {
expect(classifyProtocolFamily("application/msgpack", null)).toBe(
"messagepack",
);
});
it("classifies from path when content type is null", () => {
expect(classifyProtocolFamily(null, "/some/grpc/method")).toBe("grpc");
expect(classifyProtocolFamily(null, "/api/json-rpc/2.0")).toBe("json-rpc");
});
it("returns null for unknown protocols", () => {
expect(classifyProtocolFamily("text/plain", null)).toBeNull();
expect(classifyProtocolFamily(null, null)).toBeNull();
});
it("detects credential-like field names", () => {
expect(looksLikeCredential("password")).toBe(true);
expect(looksLikeCredential("api_key")).toBe(true);
expect(looksLikeCredential("authorization")).toBe(true);
expect(looksLikeCredential("username")).toBe(false);
});
});
describe("JSON-RPC decoding", () => {
it("decodes a simple JSON-RPC request", () => {
const payload = new TextEncoder().encode(
JSON.stringify({
jsonrpc: "2.0",
method: "add",
params: [1, 2],
id: 1,
}),
);
const result = decodeJsonRpc(payload);
expect(result.decoded_fields.length).toBe(4);
expect(result.truncated).toBe(false);
});
it("redacts credential-like fields", () => {
const payload = new TextEncoder().encode(
JSON.stringify({
password: "secret123",
username: "admin",
}),
);
const result = decodeJsonRpc(payload);
const passwordField = result.decoded_fields.find(
(f) => f.path === "password",
);
expect(passwordField?.value).toBe("[REDACTED]");
const usernameField = result.decoded_fields.find(
(f) => f.path === "username",
);
expect(usernameField?.value).toBe("admin");
});
});
describe("MessagePack decoding", () => {
it("detects map type", () => {
const payload = new Uint8Array([0x82]);
const result = decodeMessagePack(payload);
expect(result.decoded_fields[0]?.value).toBe("map");
});
it("detects array type", () => {
const payload = new Uint8Array([0x92]);
const result = decodeMessagePack(payload);
expect(result.decoded_fields[0]?.value).toBe("array");
});
it("reports unknown type for other tags", () => {
const payload = new Uint8Array([0xff]);
const result = decodeMessagePack(payload);
expect(result.decoded_fields[0]?.value).toBe("unknown");
expect(result.decoded_fields[0]?.inferred).toBe(true);
});
});
describe("gRPC frame decoding", () => {
it("decodes a valid gRPC frame header", () => {
const payload = new Uint8Array([
0x00, 0x00, 0x00, 0x00, 0x05, 1, 2, 3, 4, 5,
]);
const result = decodeGrpcFrame(payload);
expect(result.decoded_fields).toHaveLength(2);
expect(result.decoded_fields[0]?.path).toBe("compressed");
expect(result.decoded_fields[0]?.value).toBe(false);
expect(result.decoded_fields[1]?.path).toBe("message_length");
expect(result.decoded_fields[1]?.value).toBe(5);
});
it("detects compressed flag", () => {
const payload = new Uint8Array([0x01, 0x00, 0x00, 0x00, 0x0a]);
const result = decodeGrpcFrame(payload);
expect(result.decoded_fields[0]?.value).toBe(true);
});
it("handles too-short frames", () => {
const payload = new Uint8Array([0x00, 0x01]);
const result = decodeGrpcFrame(payload);
expect(result.decoded_fields[0]?.path).toBe("error");
});
});
describe("schema inference", () => {
it("infers schema from repeated messages", () => {
const messages: ProtocolMessage[] = [
{
sequence: 0,
at_ms: 0,
family: "json-rpc",
direction: "request",
endpoint: "/api",
content_type: "application/json",
raw_payload: null,
decoded_fields: [
{ path: "method", wire_type: "json", value: "add", inferred: false },
{ path: "id", wire_type: "json", value: 1, inferred: false },
],
schema_hypotheses: [],
truncated: false,
credentials_redacted: false,
},
{
sequence: 1,
at_ms: 10,
family: "json-rpc",
direction: "response",
endpoint: "/api",
content_type: "application/json",
raw_payload: null,
decoded_fields: [
{ path: "result", wire_type: "json", value: 3, inferred: false },
{ path: "id", wire_type: "json", value: 1, inferred: false },
],
schema_hypotheses: [],
truncated: false,
credentials_redacted: false,
},
];
const hypotheses = inferMessageSchema(messages);
expect(hypotheses).toHaveLength(3);
const idHypothesis = hypotheses.find((h) => h.field_name === "id");
expect(idHypothesis).toBeDefined();
expect(idHypothesis!.evidence_count).toBe(2);
expect(idHypothesis!.confidence).toBe(1);
});
});
describe("uses ProtocolCapture type", () => {
it("validates a well-formed capture typed value", () => {
const capture: ProtocolCapture = {
family: "grpc",
messages: [],
inferred_schema: [],
has_truncated: false,
credentials_detected: false,
};
expect(capture.family).toBe("grpc");
});
});
describe("protocol capture schema validation", () => {
it("validates a well-formed capture", () => {
const capture = {
family: "grpc" as const,
messages: [],
inferred_schema: [],
has_truncated: false,
credentials_detected: false,
};
const result = protocolCaptureSchema.safeParse(capture);
expect(result.success).toBe(true);
});
});