Ysonet Categorize Gadget

Categorize a ysonet gadget

Classify only facts supported by the gadget code, tests, or project documentation. Keep missing facts visible as uncategorized; never guess a more useful-looking value.

1. Read the evidence

Read:

• CLAUDE.md and the gadget sections of docs/ARCHITECTURE.md.
• The complete generator, including Generate, Options, Variants, Labels, AdditionalInfo, CommandInput, and SupportedFormatters.
• Any inner generator, bridge, helper, bundled assembly, or target type on which the gadget depends.
• Focused tests for the gadget and its variants.

Confirm whether GadgetFacetSet and GadgetFacetReader exist. If they do not, report proposed values only and say that the category implementation is pending. Do not create a parallel metadata scheme.

2. Classify effective capability units

• A gadget without variants has one unit.
• Variants with identical facts inherit the gadget facets.
• A variant with different kind, accepted input, or requirements gets a complete FacetOverride.
• Never combine one variant's formatter, input, or requirements with another's.
• A gadget that subclasses ANOTHER gadget (not GenericGenerator directly, for example ActivitySurrogateSelectorFromFile extends ActivitySurrogateSelector, and DataSetTypeSpoof extends DataSet) inherits the parent gadget's Facets() unless it overrides them. Its capability often differs from the parent, so classify it on its own evidence and give it its own Facets() instead of trusting the inherited default.

Formatter is already metadata. Start with SupportedFormatters() and remove the variant's UnsupportedFormatters.

3. Use the small vocabulary

Every declared axis can contain multiple proven values.

Payload kind

Choose broad discovery families only:

• code-execution
• file-system
• network
• information-disclosure
• denial-of-service
• nested-deserialization
• other
• uncategorized

Do not create values for an individual sink, CVE, protocol, or operation. For example, file read/write/delete can share file-system, and DNS/SMB/callbacks can share network, when the behavior is proven. A working-directory change is not automatically file-system: use other if the behavior is known but does not fit the broad vocabulary, or uncategorized if the behavior is not established.

Input type is not payload kind. Reading a source file on the generator does not make the target payload an information-disclosure gadget.

Accepted input

Use these user-provided forms:

• command
• local-file (read on the OPERATOR machine while building)
• target-path (a path only the TARGET process touches)
• unc-path
• host (a bare host name or IP the target reaches)
• remote-url
• source-code-file
• assembly-file
• none
• other
• uncategorized

Normally omit .WithInputs(...) and let the reader derive the value from the effective CommandInputType. The full table is GadgetFacetReader.DeriveInput, which has one arm per enum member:

The path types say WHOSE file system a path belongs to, and that is the one thing a user has to get right on a file gadget: local-file is read here while building, target-path is only touched by the deserializing process. Do not fold them together.

Override the derived value only when code proves additional or different forms: both local-file and unc-path for a gadget that accepts either, or remote-url plus target-path for one whose -c is a URL and whose second option names a file on the target. Distinguish a file ysonet consumes from a path the generated payload uses in the detailed help.

Requirements

Use broad target needs:

• built-in
• extra-assembly
• wpf
• net-framework
• modern-dotnet
• other
• uncategorized

Multiple requirements can apply. Do not confuse a generator build dependency with a target requirement. Keep exact assembly names, products, and versions in AdditionalInfo() or Labels().

other means a proven fact falls outside the vocabulary. uncategorized means the evidence is missing or has not been reviewed. Never combine uncategorized with another value on the same axis.

Runtime versions

This axis is the one exception to the broad-vocabulary rule: it carries exact build numbers, because "old build" does not tell an operator whether the payload lands. Tokens live in RuntimeVersion: net-fx-2.0 through net-fx-4.8.1, net-5.0 through net-10.0, mono, plus other and unspecified.

• THE VERSION DESCRIBES THE TARGET, never ysonet and never the machine the payload was built on. Ask "what does the operator have to check on the app in front of them". That is usually the framework the target PROCESS RUNS ON, but when the gate is a compile-time compatibility switch it is the framework the target APPLICATION WAS BUILT AGAINST (its TargetFrameworkAttribute). Both are versions and both get declared. DataViewManagerXxe and DataSetXxe are the worked example: EnableLegacyXmlSettings() reads the entry assembly's attribute, so an app stamped below 4.5.2 is exploitable on a fully patched machine and one stamped 4.5.2+ is not on any build - they declare 4.0 - 4.5.1, and that span is about the app. Both were wrongly left unspecified at first because the reviewer measured ysonet's own build instead of the target's.
• A new or changed runtime-gated gadget must name at least one evidence-backed working version. Test the current/latest candidate first. If it does not fire because of runtime compatibility, reproduce on older supported target versions and use the highest verified working version, never the failed latest version. Record the latest tested non-working version in AdditionalInfo() or the gadget docs.
• Use a single token when only one target version is established. Declare a contiguous span with RuntimeVersion.Range(first, last) only when evidence supports the whole span; Range refuses a reversed pair and one that crosses runtime families.
• A declaration means "reproduced or documented here", never "fails everywhere else". An unlisted version means nobody recorded it.
• Leave unspecified when the real gate is not a version at all: an OS patch (PSObject and CVE-2017-8565), a library version, or a machine-wide switch somebody can toggle. That detail belongs in AdditionalInfo(). A gate that IS a framework version threshold does not qualify, even when the threshold is on the target app's build rather than the installed runtime - declare it. For an existing gadget, missing version evidence can remain visibly unspecified; for a new runtime-gated gadget it is an unresolved finding, not a finished declaration.
• Never fill this axis in to make a gadget look better documented. unspecified is the honest and expected value for most of the catalog.

The FLOOR is measured too, not assumed

The ceiling rule above has a mirror. Most of the catalog declares a 4.0 floor because 2.0 - 3.5 is a different CLR nobody had run these on, not because anyone measured a refusal. The LEGACY test tier (ysonet.Tests.exe --legacy) measures it: it deserializes the real payload on CLR 2 in lanes for 2.0, 3.0 and 3.5.

• Cheap static check first, and it is free: a NORMAL run prints LEGACY floor candidates, the gadgets whose generated payload names NO 4.x assembly version. The most common CLR-2 blocker is an assembly VERSION string in our own payload rather than an absent type, so that list is the filter.
• Then add a row to LegacyClrRows in ysonet.Tests/Tiers/LegacyClrTier.cs (a private module uses the RunPrivateLegacyRows hook into the same engine) and run the tier.
• A gadget earns a low token only when ALL FOUR hold: the child reported Environment.Version 2.0.50727 (asserted, not assumed - the .exe.config pin is not proof); the row's real EFFECT was observed, never "no exception"; no assembly from a newer framework was recorded as loaded; and the lane's reference set matches the token being claimed.
• A net-fx-2.0 claim means 2.0 at the servicing level the run header prints. Installing 3.5 SP1 service-packs the 2.0 files in place, and a 2.0-only box is not installable on modern Windows, so a 2.0-RTM answer is out of reach here.
• Record both bounds, or say explicitly that the floor was not measured. A measured NEGATIVE is a result worth keeping: put the classified reason in AdditionalInfo() (for example "below 4.0 only BinaryFormatter and LosFormatter work, because the SOAP / NetDataContract / DataContract readers bind the payload's Version=4.0.0.0 verbatim"), never in a facet value.
• The version-evidence check is symmetric, so a floor observation is REPORTED (couldLower) rather than failing the run. Do not read a green run as "nothing to declare"; read the advisory lines.

4. Apply requested changes

When the user asks for edits:

1. Override Facets() for the normal gadget facts. Build the set fluently: new GadgetFacetSet().WithKinds(...).WithRequirements(...). Each WithKinds, WithInputs, WithRequirements, and WithVersions REPLACES its whole axis. The constructor defaults Kinds and Requirements to uncategorized, Versions to unspecified, and leaves Inputs null so the reader derives accepted input from the effective CommandInputType. Omit WithInputs(...) whenever that derived value is correct, and omit WithVersions(...) unless the evidence names versions.
2. Add a complete FacetOverride only to a variant that differs, via variant.WithFacets(new GadgetFacetSet()...). The override must declare full Kinds, Requirements, and Versions (it replaces the whole set, so a version the gadget declared is lost unless repeated); leave its Inputs null when the variant's effective Input derives the right value.
3. Keep metadata beside the gadget; do not add a production name-to-facet table.
4. Correct stale Labels() or AdditionalInfo() found during the review.
5. Update the gadget row and facet contract in docs/ARCHITECTURE.md.
6. Add focused coverage for meaningful variant distinctions or new values.
7. Confirm --category=axis=value, filtered --list gadgets, and gadget help expose each effective unit correctly.
8. Run the project's normal Debug build.

Do not change payload generation to make a category convenient. Do not add plugin metadata. For a catalog-wide consistency review, use $ysonet-audit-gadget-metadata.

5. Report the result

Report one row per effective unit:

Call out inherited facts, every uncategorized or unspecified axis and its missing evidence, exact target dependencies, changed files, and verification results.

Final checks

• Every fact has code, test, or project-documentation evidence.
• Values are broad, and multiple proven values are retained.
• Input is derived unless an override is necessary.
• Variants remain internally consistent.
• other and uncategorized retain different meanings.
• Every new runtime-gated gadget names at least one verified working version; if latest failed, the highest verified working and latest tested non-working versions are recorded.
• Runtime versions are declared only where evidence names them, with a single token or an evidence-backed contiguous range, never to look complete.
• Formatter values match effective variant support.
• No plugin facet work was introduced.