maltego-transform-author

Authoring Maltego transforms

Read docs/transform-authoring.md before writing code. It is the canonical guidance and this skill does not restate it — a second copy would drift. This file exists to make sure the checklist below is applied every time, because two of the failure modes report success while producing nothing.

Non-negotiables

1. Return a list, never a MaltegoGraph. A graph returned from an async transform is silently discarded: zero entities, run still reports COMPLETED (success). Use -> list[A | B | C]; the union still publishes every output type to discovery.

2. Annotate both sides. Input type comes from the first parameter's annotation, output from the return annotation. A bare -> list advertises no output type, so the transform appears with output NONE and the Maltego client cannot route it.

3. Import the module in server/project.py, with the other imports at the top of the file. The server registers only what project.py imports — the most common reason a new transform never appears. Do not append the import to the end of the file: it lands after the if __name__ == "__main__" block and registers nothing.

4. Check the entity count, not the success state. run_transform prints Entities (N). Confirm N > 0.

5. Credentials go in TransformSetting(auth=True, is_global=True), read at runtime via settings.get(NAME, ""). Never hardcode a key. Declare the setting name once as a module constant and use it on both sides — a literal mistyped on one side silently reads back as the default. Pass the list to register_transform as settings=[...] — not transform_settings=, which raises at import and stops the server booting.

   Confirm the field actually reaches the client, or a user cannot enter the credential at all. Restart, then check discovery publishes a transformSettings array:

   curl -sk https://127.0.0.1:3000/api/v3/transforms | grep -o '"transformSettings":[^]]*]'