diff --git a/README.md b/README.md index fd2f1c4af..d398d8568 100644 --- a/README.md +++ b/README.md @@ -369,6 +369,21 @@ REA gives the agent a clear path from that request to working code: REA handles the app analysis in steps 1 through 5. The agent performs step 6 with its normal file-editing and test tools, using what it learned about the app. +## Showcase + +### DX-Ball: game reconstruction (in progress) + +[DX-Ball](https://github.com/N0zoM1z0/dx-ball) follows the journey from a classic +Windows game's executable to maintainable C. Using REA's Ghidra provider, the +project traces functions, game state and dependencies, then checks reconstructed +behavior with original-x86 differential tests and pinned-compiler replay. + +A [sound-pan investigation](https://github.com/N0zoM1z0/dx-ball/blob/main/docs/GAMEPLAY_OWNER.md) +turns incomplete pseudocode into a C implementation that passes 3,205 original-x86 +cases and reproduces all 63 compiled function bytes. Follow its +[REA workflow](https://github.com/N0zoM1z0/dx-ball/blob/main/docs/REA.md) +from binary evidence to reconstruction. + ## What agents can do - Investigate a feature you like and build a version tailored to your own product. diff --git a/src/domain/javascriptStaticAnalysisCalls.ts b/src/domain/javascriptStaticAnalysisCalls.ts index f669548a2..4208307b1 100644 --- a/src/domain/javascriptStaticAnalysisCalls.ts +++ b/src/domain/javascriptStaticAnalysisCalls.ts @@ -162,7 +162,7 @@ const inspectEndpointCall = ( value: first, mechanism: `call:${name}`, }); - const endpoint = endpointArgumentHelper(name, node.arguments); + const endpoint = endpointArgumentHelper(name, node.arguments, node.callee); if (endpoint !== undefined) addEndpoint(context, { node, diff --git a/src/domain/javascriptStaticAnalysisHelpers.ts b/src/domain/javascriptStaticAnalysisHelpers.ts index d13d2a7ac..c7085e2af 100644 --- a/src/domain/javascriptStaticAnalysisHelpers.ts +++ b/src/domain/javascriptStaticAnalysisHelpers.ts @@ -363,32 +363,75 @@ const isRequestUrlLiteral = (value: string): boolean => value.startsWith("./") || value.startsWith("../"); +/** + * Browsing-context and document `open` take a URL or type first and a target + * name second. The name is only a spelling, since `parent` or `self` may be a + * local XHR binding, so it never overrides a literal HTTP method. + */ +const WINDOW_OPEN_CALL = + /(?:^|\.)(?:window|self|globalThis|top|parent|opener|frames|document)\.open$/u; + /** * Read `XMLHttpRequest.open(method, url)`. `fs.open(path, "r")` and * `window.open(url, "_blank")` share the callee name, so a literal method - * must be an HTTP method, and a computed method needs a request URL literal. - * XHR normalizes the standard methods' case; extension methods such as - * WebDAV `PROPFIND` are conventionally uppercase tokens. + * must be an HTTP method, and a computed method needs a request URL literal + * on a receiver not spelled as a browsing context. XHR normalizes the + * standard methods' case; extension methods such as WebDAV `PROPFIND` are + * conventionally uppercase tokens. */ const xhrOpenUrl = ( + name: string, methodNode: t.Node | null | undefined, urlNode: t.Node | null | undefined, ): string | undefined => { const url = stringValue(urlNode); if (url === undefined) return undefined; const method = stringValue(methodNode); - if (method === undefined) return isRequestUrlLiteral(url) ? url : undefined; + if (method === undefined) + return !WINDOW_OPEN_CALL.test(name) && isRequestUrlLiteral(url) + ? url + : undefined; return XHR_METHODS.has(method.toUpperCase()) || /^[A-Z][A-Z-]*$/u.test(method) ? url : undefined; }; +const KEYED_COLLECTION_CONSTRUCTORS = new Set([ + "FormData", + "Headers", + "Map", + "Set", + "URLSearchParams", + "WeakMap", + "WeakSet", +]); + /** - * Browsing-context and document `open` take a URL or type first and a target - * name second, never an XHR method and request URL. + * Whether a get/delete receiver is spelled as a keyed collection: a + * constructed Map, Set, Headers, FormData, or URLSearchParams, or a + * `headers`/`searchParams` property. Spelling alone does not prove the + * binding, so callers keep URL and path literals as requests. */ -const WINDOW_OPEN_CALL = - /(?:^|\.)(?:window|self|globalThis|top|parent|opener|frames|document)\.open$/u; +const isKeyedCollectionReceiver = (callee: t.Node): boolean => { + if (!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee)) + return false; + const receiver = callee.object; + if (t.isNewExpression(receiver)) + return ( + t.isIdentifier(receiver.callee) && + KEYED_COLLECTION_CONSTRUCTORS.has(receiver.callee.name) + ); + if ( + !t.isMemberExpression(receiver) && + !t.isOptionalMemberExpression(receiver) + ) + return false; + const property = semanticStaticPropertyName( + receiver.property, + receiver.computed, + ); + return property === "headers" || property === "searchParams"; +}; /** Select the literal URL argument for recognized network callees. */ export const endpointArgument = ( @@ -399,17 +442,25 @@ export const endpointArgument = ( | t.JSXNamespacedName | t.ArgumentPlaceholder )[], + callee: t.Node, ): string | undefined => { if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket") return stringValue(args[0]); - if (name.endsWith(".open") && !WINDOW_OPEN_CALL.test(name)) - return xhrOpenUrl(args[0], args[1]); - if ( - ["get", "post", "put", "patch", "delete", "request"].some( - (method) => name === method || name.endsWith(`.${method}`), - ) - ) - return stringValue(args[0]); + if (name.endsWith(".open")) return xhrOpenUrl(name, args[0], args[1]); + const method = ["get", "post", "put", "patch", "delete", "request"].find( + (candidate) => name === candidate || name.endsWith(`.${candidate}`), + ); + if (method !== undefined) { + const value = stringValue(args[0]); + // Only get and delete also belong to the keyed-collection APIs, whose + // keys are header, field, and parameter names rather than URLs or paths. + return value !== undefined && + (method === "get" || method === "delete") && + !isRequestUrlLiteral(value) && + isKeyedCollectionReceiver(callee) + ? undefined + : value; + } if (name.endsWith("loadURL")) return stringValue(args[0]); return undefined; }; diff --git a/src/domain/webBundleAnalyzer.test.ts b/src/domain/webBundleAnalyzer.test.ts index d4f5440be..e8f038d69 100644 --- a/src/domain/webBundleAnalyzer.test.ts +++ b/src/domain/webBundleAnalyzer.test.ts @@ -188,6 +188,8 @@ describe("web bundle static-analysis parity", () => { window.open(url, "/preview"); globalThis.open(url, "./frame"); document.open("text/html", "/replace"); + parent.open("GET", "/parent-xhr"); + self.open("post", "/self-xhr"); `), ); expect( @@ -195,11 +197,47 @@ describe("web bundle static-analysis parity", () => { ).toEqual([ "/dav/", "/dynamic-method", + "/parent-xhr", + "/self-xhr", "/xhr-get", "https://xhr.example.test/submit", ]); }); + it("keeps HTTP-method-named reads of provable keyed collections out of endpoints", () => { + const result = analyzeCapturedWebBundle( + inspection(` + axios.get("https://api.example.test/users"); + api.get("users"); + client.delete("cache-key"); + new Map().get("map-key"); + new URLSearchParams(location.search).get("q"); + new Headers(init).delete("x-trace"); + new FormData(form).get("file"); + response.headers.get("content-type"); + request?.headers.delete("cookie"); + new URL(location.href).searchParams.get("page"); + api.headers.post("/v1/headers"); + api.searchParams.request("/search"); + new Headers().get("/users"); + api.headers.get("https://api.example.test/headers"); + api.searchParams.delete("../search"); + `), + ); + expect( + result.observations.endpoints.map(({ value }) => value).sort(), + ).toEqual([ + "../search", + "/search", + "/users", + "/v1/headers", + "cache-key", + "https://api.example.test/headers", + "https://api.example.test/users", + "users", + ]); + }); + it("recognizes loadURL endpoints like static analysis", () => { const result = analyzeCapturedWebBundle( inspection('window.win.loadURL("https://embedded.test/app");'), diff --git a/src/domain/webBundleAnalyzerInspection.ts b/src/domain/webBundleAnalyzerInspection.ts index 85eb2d011..4f8451181 100644 --- a/src/domain/webBundleAnalyzerInspection.ts +++ b/src/domain/webBundleAnalyzerInspection.ts @@ -147,7 +147,7 @@ const inspectCall = ( accumulator, }); } - const endpoint = endpointArgument(name, node.arguments); + const endpoint = endpointArgument(name, node.arguments, node.callee); if (endpoint !== undefined) addFinding({ collection: accumulator.endpoints,