fix(ghidra): classify modern Swift manglings in swift type analysis (#1208)

* fix(ghidra): classify modern Swift manglings in swift type analysis

Categorize modern Swift 4.2+ manglings ($s, _$s) instead of dropping them
in analyze_swift_types. The classifier only accepted the legacy _Tt marker,
so procedure names reported by current providers produced an empty inventory.
Legacy _Tt families and behavior are unchanged. Fixes #1187.

* fix(swift): retain provider aliases and category unknowns

---------

Co-authored-by: Saim Shafique <sx4imm@gmail.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
Saim Shafique
2026-10-09 16:10:55 +08:00
committed by GitHub
co-authored by Saim Shafique morluto
parent 04a516b1e3
commit 6935dc7fe1
13 changed files with 968 additions and 31 deletions
+25 -3
View File
@@ -8,6 +8,7 @@ import type { EnhancedToolName } from "../contracts/enhancedInputs.js";
import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
@@ -358,9 +359,30 @@ export class EnhancedTools {
signal?: AbortSignal,
): EnhancedResult {
const procedures = await this.#allAddressed("list_procedures", signal);
return procedures.ok
? ok(categorizeSwiftTypes(procedures.value, input))
: procedures;
if (!procedures.ok) return procedures;
const symbols = await this.#allAddressed("list_names", signal);
if (
!symbols.ok &&
!(symbols.error instanceof AnalysisCapabilityUnavailableError)
)
return symbols;
const result = categorizeSwiftTypes(
procedures.value,
input,
symbols.ok ? symbols.value : [],
);
return ok(
symbols.ok
? result
: {
...result,
symbol_inventory_error: projectAnalysisError(symbols.error),
limitations: [
...result.limitations,
"The provider's symbol inventory is unavailable; demangled procedures could not be joined to their Swift aliases.",
],
},
);
}
async #findXrefs(name: string, signal?: AbortSignal): EnhancedResult {
+4 -2
View File
@@ -30,12 +30,14 @@ export const enhancedInputSchemas = {
category: z
.enum(["classes", "structs", "enums", "protocols", "extensions", "other"])
.optional()
.describe("Limit results to one Swift symbol category."),
.describe(
"Limit categorized results to one Swift category; unresolved category observations remain in unclassified.",
),
pattern: z
.string()
.optional()
.describe(
"Case-sensitive literal filter applied to mangled symbol names.",
"Case-sensitive literal filter applied to provider procedure names and their supporting Swift manglings.",
),
}),
find_xrefs_to_name: z.strictObject({ name: z.string() }),
+1 -1
View File
@@ -54,7 +54,7 @@ export const ENHANCED_TOOL_CONTRACTS = [
),
enhanced(
"analyze_swift_types",
'Categorize analyzed procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Returns deduplicated names grouped with counts. Optionally select one category and/or apply a case-sensitive literal name filter; for example, use {category: "classes", pattern: "Account"} to find matching class symbols.',
'Categorize analyzed Swift procedure names using their manglings or same-address Swift symbol aliases. Decodes legacy and literal modern nominal contexts into classes, structs, enums, protocols, and extensions. Preserves provider names and supporting mangled_names; unresolved categories appear in other and in unclassified, which remains inline even under category filters. Returns deduplicated procedure-name counts, not unique source types, plus identification limitations. Optionally select one category and/or apply a case-sensitive literal filter to provider names or supporting manglings; for example, use {category: "structs", pattern: "Pair"}.',
enhancedInputSchemas.analyze_swift_types,
),
enhanced(
+13 -1
View File
@@ -283,9 +283,21 @@ export const enhancedOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
z.string(),
z.object({
count: z.number().int().min(0),
items: z.array(addressedEntry),
items: z.array(
addressedEntry.extend({
mangled_names: z.array(z.string()),
}),
),
}),
),
unclassified: z.array(
addressedEntry.extend({
mangled_names: z.array(z.string()),
reason: z.enum(["category_not_decoded", "conflicting_categories"]),
}),
),
limitations: z.array(z.string()),
symbol_inventory_error: analysisErrorProjectionSchema.exactOptional(),
}),
),
find_xrefs_to_name: resultOf(
+70
View File
@@ -0,0 +1,70 @@
const LEGACY_CATEGORIES = [
["_TtC", "classes"],
["_TtV", "structs"],
["_TtO", "enums"],
["_TtP", "protocols"],
["_TtE", "extensions"],
] as const;
/** Supported procedure categories derived from Swift symbol encodings. */
export type SwiftTypeCategory = (typeof LEGACY_CATEGORIES)[number][1] | "other";
const NOMINAL_CATEGORIES: ReadonlyMap<string, SwiftTypeCategory> = new Map([
["C", "classes"],
["V", "structs"],
["O", "enums"],
["P", "protocols"],
]);
/**
* Recognize Swift manglings and decode literal module/nominal contexts.
* Substitutions, generic contexts, and other encodings remain unknown.
*/
export const classifySwiftSymbol = (
name: string,
): { readonly category: SwiftTypeCategory | null } | undefined => {
const prefix = /^_?(?:\$[sS]|_T0)/u.exec(name);
if (prefix === null) {
if (!name.includes("_Tt")) return undefined;
return {
category:
LEGACY_CATEGORIES.find(([prefix]) => name.startsWith(prefix))?.[1] ??
null,
};
}
const mangling = name.slice(prefix[0].length);
let offset = identifierEnd(mangling, 0);
if (offset === undefined) return { category: null };
let category: SwiftTypeCategory | null = null;
for (;;) {
const end = identifierEnd(mangling, offset);
if (end === undefined) break;
const kind = mangling.charAt(end);
const nominal = NOMINAL_CATEGORIES.get(kind);
if (nominal === undefined) {
if (kind === "E" && category !== null) category = "extensions";
break;
}
category = nominal;
offset = end + 1;
}
return { category };
};
const identifierEnd = (
mangling: string,
offset: number,
): number | undefined => {
const lengthToken = /^[1-9][0-9]*/u.exec(mangling.slice(offset))?.[0];
if (lengthToken === undefined) return undefined;
const start = offset + lengthToken.length;
const end = start + Number(lengthToken);
// Swift identifiers with substitutions/punycode need a fuller decoder.
if (
!Number.isSafeInteger(end) ||
end > mangling.length ||
!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(mangling.slice(start, end))
)
return undefined;
return end;
};
+161
View File
@@ -80,4 +80,165 @@ describe("symbol analysis", () => {
},
});
});
it("classifies modern Swift manglings reported by current providers", () => {
const result = categorizeSwiftTypes([
{ address: "0x1000009f8", name: "$s4main4PairVMa" },
{ address: "0x100000ac4", name: "$s4main6ScorerVMa" },
{ address: "0x100000ab4", name: "_$s4main4PairVMa" },
{ address: "0x1", name: "_TtCClass" },
{ address: "0x1000009f8", name: "$s4main4PairVMa" },
]);
expect(result).toMatchObject({
total: 4,
categories: {
classes: { count: 1 },
structs: {
count: 3,
items: [
{ address: "0x1000009f8", name: "$s4main4PairVMa" },
{ address: "0x100000ac4", name: "$s4main6ScorerVMa" },
{ address: "0x100000ab4", name: "_$s4main4PairVMa" },
],
},
},
});
});
it("keeps non-Swift procedure names out of the Swift inventory", () => {
const result = categorizeSwiftTypes([
{ address: "0x1", name: "printf" },
{ address: "0x2", name: "_OBJC_CLASS_$_App" },
{ address: "0x3", name: "std::vector<int>::push_back" },
]);
expect(result).toMatchObject({ total: 0 });
});
});
describe("modern Swift category evidence", () => {
it.each([
["$s4main4PairVMa", "structs"],
["_$s4main6ScorerVMa", "structs"],
["$s4main7ServiceCMa", "classes"],
["$s4main5StateOMa", "enums"],
["$s4main7ScoringPMp", "protocols"],
["$s4main5OuterV5InnerCMa", "classes"],
["$s4main4PairV5otherE7doubledSiyF", "extensions"],
["$S4main4PairVMa", "structs"],
["_T04main4PairVMa", "structs"],
["$s4_TtX4PairVMa", "structs"],
] as const)("decodes nominal contexts for %s", (name, category) => {
expect(
categorizeSwiftTypes([{ address: "0x1", name }], { category }),
).toMatchObject({
total: 1,
categories: { [category]: { count: 1 } },
unclassified: [],
});
});
it("retains unresolved Swift observations under category filters", () => {
const names = [
"$s4main13swiftIndirectySiAA7Scoring_p_SitF",
"$sSi4mainE7doubledSiyF",
"$s9999999999999999999999BadVMa",
"$s4main04PairVMa",
];
const result = categorizeSwiftTypes(
names.map((name, index) => ({ address: String(index), name })),
{ category: "structs" },
);
expect(result).toMatchObject({
total: 0,
unclassified: names.map((name) => ({
name,
mangled_names: [name],
reason: "category_not_decoded",
})),
limitations: expect.arrayContaining([
expect.stringContaining("could not be established"),
]),
});
expect(
categorizeSwiftTypes([{ address: "0x1", name: names[0] ?? "" }], {
category: "structs",
pattern: "missing",
}),
).toMatchObject({ total: 0, unclassified: [] });
});
it("joins Swift aliases only at the exact procedure address", () => {
const result = categorizeSwiftTypes(
[
{ address: "0x1", name: "main::Pair::typeMetadataAccessor" },
{ address: "0x2", name: "std::vector<int>::push_back" },
{ address: "0x3", name: "main::Pair::other" },
],
{ category: "structs", pattern: "Pair" },
[
{ address: "0x1", name: "_$s4main4PairVMa" },
{ address: "0x4", name: "$s4main4PairVMa" },
],
);
expect(result).toMatchObject({
total: 1,
categories: {
structs: {
items: [
{
address: "0x1",
name: "main::Pair::typeMetadataAccessor",
mangled_names: ["_$s4main4PairVMa"],
},
],
},
},
unclassified: [],
});
});
it("deduplicates display names after selecting a category", () => {
expect(
categorizeSwiftTypes(
[
{ address: "0x1", name: "shared" },
{ address: "0x2", name: "shared" },
],
{ category: "structs" },
[
{ address: "0x1", name: "$s4main7ServiceCMa" },
{ address: "0x2", name: "$s4main4PairVMa" },
],
),
).toMatchObject({
total: 1,
categories: { structs: { items: [{ address: "0x2", name: "shared" }] } },
});
});
});
describe("Swift alias ambiguity", () => {
it("reports conflicting aliases rather than choosing a category", () => {
expect(
categorizeSwiftTypes(
[{ address: "0x1", name: "shared" }],
{ category: "structs" },
[
{ address: "0x1", name: "$s4main4PairVMa" },
{ address: "0x1", name: "$s4main7ServiceCMa" },
],
),
).toMatchObject({
total: 0,
unclassified: [
{
name: "shared",
reason: "conflicting_categories",
mangled_names: ["$s4main4PairVMa", "$s4main7ServiceCMa"],
},
],
});
});
});
+86 -24
View File
@@ -1,5 +1,9 @@
import type { JsonValue } from "./jsonValue.js";
import type { AddressedName } from "./hopperValues.js";
import {
classifySwiftSymbol,
type SwiftTypeCategory,
} from "./swiftSymbolClassification.js";
/** Select and deduplicate Objective-C class labels. */
export const discoverObjcClasses = (
@@ -34,50 +38,108 @@ export const discoverObjcProtocols = (
};
};
const SWIFT_CATEGORIES = [
["classes", "_TtC"],
["structs", "_TtV"],
["enums", "_TtO"],
["protocols", "_TtP"],
["extensions", "_TtE"],
] as const;
type SwiftTypeCategory = (typeof SWIFT_CATEGORIES)[number][0] | "other";
/** Categorize deduplicated Swift mangled symbols. */
/** Categorize procedure names using Swift manglings at their exact addresses. */
export const categorizeSwiftTypes = (
procedures: readonly AddressedName[],
filter: {
readonly category?: SwiftTypeCategory | undefined;
readonly pattern?: string | undefined;
} = {},
): JsonValue => {
const groups: Record<string, AddressedName[]> = Object.fromEntries(
[...SWIFT_CATEGORIES.map(([category]) => category), "other"].map(
symbols: readonly AddressedName[] = [],
) => {
const groups: Record<
string,
Array<{
address: string;
name: string;
mangled_names: string[];
}>
> = Object.fromEntries(
["classes", "structs", "enums", "protocols", "extensions", "other"].map(
(category) => [category, []],
),
);
const aliases = swiftAliasesByAddress(symbols);
const pattern = filter.pattern;
const seen = new Set<string>();
const unclassifiedNames = new Set<string>();
const unclassified: Array<{
address: string;
name: string;
mangled_names: string[];
reason: "category_not_decoded" | "conflicting_categories";
}> = [];
for (const entry of procedures) {
if (!entry.name.includes("_Tt") || seen.has(entry.name)) continue;
const category =
SWIFT_CATEGORIES.find(([, prefix]) =>
entry.name.startsWith(prefix),
)?.[0] ?? "other";
if (filter.category !== undefined && filter.category !== category) continue;
if (filter.pattern !== undefined && !entry.name.includes(filter.pattern))
if (seen.has(entry.name)) continue;
const mangledNames = [
...new Set([
...(classifySwiftSymbol(entry.name) === undefined ? [] : [entry.name]),
...(aliases.get(entry.address) ?? []),
]),
];
if (mangledNames.length === 0) continue;
if (
pattern !== undefined &&
![entry.name, ...mangledNames].some((name) => name.includes(pattern))
)
continue;
seen.add(entry.name);
groups[category]?.push(entry);
const kinds = new Set(
mangledNames.map((name) => classifySwiftSymbol(name)?.category ?? null),
);
const category = kinds.size === 1 ? ([...kinds][0] ?? null) : null;
const item = {
address: entry.address,
name: entry.name,
mangled_names: mangledNames,
};
if (category === null && !unclassifiedNames.has(entry.name)) {
unclassifiedNames.add(entry.name);
unclassified.push({
...item,
reason:
kinds.size > 1 && !kinds.has(null)
? "conflicting_categories"
: "category_not_decoded",
});
}
const bucket = category ?? "other";
if (filter.category === undefined || filter.category === bucket) {
seen.add(entry.name);
groups[bucket]?.push(item);
}
}
const categories = Object.fromEntries(
Object.entries(groups).map(([category, items]) => [
category,
{ count: items.length, items: items.map(toJsonEntry) },
{ count: items.length, items },
]),
);
return { total: seen.size, categories };
return {
total: Object.values(groups).reduce((sum, items) => sum + items.length, 0),
categories,
unclassified,
limitations: [
"Identification uses Swift mangled procedure names or same-address symbol aliases. Demangled names without retained Swift manglings cannot be identified. Counts deduplicate procedure names, not source declarations.",
...(unclassified.length === 0
? []
: [
"Some Swift categories could not be established from the retained manglings. Unclassified observations remain inline regardless of the category filter.",
]),
],
};
};
const swiftAliasesByAddress = (symbols: readonly AddressedName[]) => {
const aliases = new Map<string, string[]>();
for (const { address, name } of symbols) {
if (classifySwiftSymbol(name) === undefined) continue;
const existing = aliases.get(address);
if (existing === undefined) aliases.set(address, [name]);
else existing.push(name);
}
return aliases;
};
const uniqueByName = (entries: readonly AddressedName[]): AddressedName[] => {