Skip to content

Expose all MCRITweb workflows and administration through the token API - #346

Open
r0ny123 wants to merge 2 commits into
masterfrom
feat/api-parity-345
Open

r0ny123 wants to merge 2 commits into
masterfrom
feat/api-parity-345

Conversation

@r0ny123

@r0ny123 r0ny123 commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #345.

The token API could perform only part of the workflows available in the browser. This adds 103 operations covering the 70 current UI routes: account setup and preferences, corpus browsing and edits, analysis submission and results, LinkHunt, YARA, diagrams and function graphs/diffs, query promotion, import/export, and user/server administration.

  • Dispatch and permissions share an explicit route table. Tests compare it with every current UI route and public McritClient operation, excluding client-local configuration methods, and check that no API operation needs a lower role than the UI route it stands for. The one listed exception is data.submit_or_query mapping to the visitor-level POST query, as analyze.query is visitor-level.
  • Browser and API workflows reuse account/admin services, result filtering, YARA generation, query-promotion logic and the diagram cache's membership check. Token identity takes precedence over cookies or a supplied username; pending accounts can access only their own account/preferences.
  • Validate bodies, identifiers, selectors and file identities before backend or filesystem actions. Apply the UI's role upload limits, bounded metadata schemas, password throttling, atomic first-user setup, token rotation and root-account protections. Local administration remains usable when the backend is unavailable.
  • Role choices that follow the UI:
    • A diagram is rendered only for a family, sample or function the report matched; any other id gets 404 and writes no file, as on the result page.
    • samples/<id>/smda and samples/<id>/binary need a contributor, as the corpus export does; no lower UI role can download what a sample was submitted as.
    • A role with a query upload cap cannot rerun query jobs. A job records only a username, and usernames are renamed and reused (ADR-0007), so there is no safe test of whose upload it was.
  • /api is exempt from CSRF because a cross-site request cannot send an apitoken. The two routes that take none, auth/token and auth/register, accept only application/json and answer anything else with 415, so a form on another site cannot configure a fresh instance.
  • Preserve backend JSON bytes/status codes, return gateway errors without HTML redirects, and avoid forwarding backend cookies. Malformed integers in job listings and in band_df_cutoff get 400 rather than a default or a value forwarded as typed. GET matches/function/<id> forwards to getMatchFunctionVs(id, None) as on master. Maintenance uses POST on this API. Version-dependent tags, reruns and extended backend options return 501 when unsupported; GET /api/capabilities describes available operations.
  • Document endpoints and compatibility behavior in docs/api.md.

Measured validation:

  • Full web suite at the current head, with MCRIT 1.16.0: 3,020 passed, 10 skipped. The 10 skips are the 6 operations that return 501 on that version (tags ×3, rerun, unique-blocks POST ×2).
  • ruff check . and git diff --check passed.
  • On the first commit (da372e3): API compatibility with MCRIT 1.12.0, 560 passed and 10 skipped, and with the MCRIT Draw the function comparison's graphs when they come into view #308 integration head, 570 passed. Also 68 live checks against an isolated real Falcon backend behind Waitress with MemoryStorage/LocalQueue, including query promotion, result workflows, exports and admin actions. Production MongoDB was not exercised.

Based on current master, 8fd5a8c, and validated with current MCRIT main, 37d69c42fb94b508f54d4f2db022942a0f46a2e5. The companion LocalQueue statistics fix discovered during live validation is familiary/mcrit#317.

- The API diagram workflow rendered any famid/samid/funid it was given,
  so any visitor could add one PNG per id to the unbounded diagram cache
  (the 1.7.0 fix from #145, reopened). The report-membership check is
  now data.diagram_filter_in_report, shared by data.diagram_file and the
  API; an id the report did not match gets 404 and writes no file.

- /api is exempt from CSRF because a cross-site request cannot carry an
  apitoken, but auth/token and auth/register take none. A plain HTML form
  could post to them, and on a fresh instance create the admin and set
  the backend URL. Both now accept only application/json and answer
  anything else with 415. No other /api route works without a token.

- samples/<id>/smda and samples/<id>/binary need a contributor. Below
  that, the UI has no way to download what a sample was submitted as;
  only the contributor-level corpus export does.

- A role with a query upload cap may no longer rerun query jobs at all.
  The ownership test compared job.username with the caller's name, and
  usernames are renamed and reused (ADR-0007), so whoever took a freed
  or renamed name passed it. With no stable owner there is no safe test.

- testApiSurfaceCoverage now checks that every API operation a UI route
  maps to needs at least that route's role in routePolicy.py. The one
  exception, data.submit_or_query mapping to the visitor-level POST
  query, is listed with its reason (analyze.query is visitor-level).

- GET matches/function/<id> forwards to getMatchFunctionVs(id, None)
  again, as on master, instead of queueing a whole-sample match job.

- The browser's promote_query error redirect uses the backend's job id
  again, not the id as typed.

- Malformed integers in query_options (start/limit on jobs) get 400
  instead of silently becoming the default.
  band_df_cutoff_coverage checks its band_df_cutoff the same way the
  matching options do, instead of forwarding it as typed.

- Remove the unused CONTRIBUTOR_ONLY and requires_contributor, and the
  job-export branch of specific_export that its route can never reach.
  Correct AGENTS.md, which still pointed at CONTRIBUTOR_ONLY, and the
  comments saying pending tokens get nothing: they reach their own
  account and capabilities. docs/api.md describes all of the above.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The API cannot do what the web UI does for the same user: unique blocks, deletion, editing samples and families, cross-compare, binary submission

1 participant