Hypatia

Hypatia is a local tool that guides an AI researcher through a security review of source code. It defines and previews the intended scope, saves the investigation and its evidence, controls each step, and closes the review after the final checks pass.

Runs locally AI-assisted security review Linked source evidence Persistent investigation memory

Profiles support smart-contract, protocol, browser, native, and broader source-code reviews based on the target's language and build evidence.

Follow the four phases of a solo investigation

A vulnerability hunt is a structured search for security flaws. In solo mode, Hypatia uses four stages: understand the code, explore possible weaknesses, investigate promising cases, and try to disprove them.

01

CONTEXT-BUILD

Map the target

Understand the code: map the production files included in the review and write the investigation plan and source-derived model.

02

EXPLORE

Explore possible weaknesses

Explore possible weaknesses: ask what-if questions, inspect exact source locations, and either reject unsupported ideas or create candidates for deeper review.

03

DEEP-DIVE

Investigate a promising case

Investigate a promising case: trace it through the target code, test its assumptions, and reject it when the source evidence is insufficient.

04

SCRUTINIZE

Try to disprove the claim

Try to disprove the remaining case. Record test results or evidence from the code structure, then write a confirmed report when that evidence supports it.

Coordinate the team and close the run

These operations sit around the research sequence rather than adding more research phases.

TEAM MODE

Team mode adds two coordination stages: TEAM-LEAD assigns the work and TEAM-SYNTHESIS combines the results.

RUN CLOSURE

Closure follows the four research stages as a runtime operation. From EXPLORE, the researcher requests HUNT_EXHAUSTED, which runs five automatic checks: memory, advisor, strict coverage, report, and consistency.

See how the researcher and runtime divide the work

The AI investigates and writes the analysis. The Hypatia software checks the rules, saves progress, and controls which workflow changes are valid.

What does the AI researcher investigate?

  • 01Maps and inspects the target source.
  • 02Develops hypotheses and records why paths were explored or rejected.
  • 03Records exact source locations and observed test results or evidence from the code structure.
  • 04Writes investigation, candidate, proof, and report artifacts.

What does the Hypatia runtime enforce?

  • 01Validates the hunt configuration, called a profile, and selected prerequisites.
  • 02Shows the intended scope, including files planned for review and exclusion, before setup.
  • 03Enforces directives, legal transitions, and required artifact structure.
  • 04Maintains persistent system and investigation memory, validates links between records, journals lifecycle changes, and runs closure gates.

Operators review the scope preview before setup. Acceptance is a procedural operator decision.

Follow the evidence

How does a possible flaw become a confirmed finding?

An idea about a possible flaw begins as a lead. It becomes a confirmed finding when inspection of the actual source code and supporting evidence sustain it.

Investigate the hypothesis

Inspect the target, record the reasoning path, and link the exact source locations that bear on the claim.

Reject unsupported paths

Record the rejection reason and preserve the decision so future work can build on it.

Advance supported candidates

Advance through DEEP-DIVE and SCRUTINIZE. Produce a confirmed report when the source and its test results or structural evidence support the claim.

Keep every decision connected to its evidence

Hypatia stores the system model, reasoning, evidence, decisions, coverage, issues, and next action in the local run. This gives a fresh researcher enough context to understand the completed work, review open questions, and continue from persisted state.

Preserve the system model

Preserves the system map, connected paths, assumptions, planned attack surfaces, current phase, and handoff state across sessions.

Trace the investigation

Records questions, what-if branches, code paths, decisions, evidence references, and follow-up questions.

Track source coverage

Tracks the exact source locations inspected, links them to the related reasoning, and shows which planned attack surfaces have source-backed coverage.

Record the proof

Records whether a possible flaw was demonstrated, disproved, informational, or left to human judgment, together with supporting source locations and test evidence.

Write the finding

Contain the final structured explanation and proof links. Hypatia checks their completeness and connections. Final security judgment stays grounded in target source and reviewed evidence.

Attach supporting evidence

Supporting proof may take the form of an executable proof of concept, focused test results, or evidence from the source-code structure.

Cross-round memory carries prior findings, rejections, coverage, and handoff summaries into later reviews for continuity and deduplication.

Run, recover, and close every investigation safely

Starting, continuing, cancelling, restoring, and closing a hunt are recorded to provide a safe recovery path for interrupted changes. A local CLI and dashboard expose status, reasoning, evidence, candidates, coverage, reports, recovery, and human feedback.

Start from a reviewed scope

Validate the profile, render and review the scope preview, then run setup.

Resume from persisted state

Inspect status, review informational phase advice, and resume persisted state. Next-round drafts require human review and never auto-start.

Cancel or restore safely

Cancel publishes a restorable archive. Restore reactivates it. Resume, cancel, and restore journal their changes transactionally.

Close only after the final checks

Run checks for memory continuity, phase advice, strict coverage, report quality, and consistency from an EXPLORE closure request.

Record every lifecycle change

Lifecycle updates move through prepared, staged, publishing, completed, rollback, or blocked states and leave a journal for recovery inspection.

Diagnose the safest next action

Recovery reports one of four outcomes: safe to resume, ready to finalize, complete, or needs repair before work continues.

Provenance auditing and recovery are available as operator workflows alongside automatic closure validation.

Use context to guide the search, then prove findings against the target

Context helps focus the research. Findings depend on the current target and evidence tied to it.

Guide the search with human and external intelligence

Human guidance and optional vulnerability intelligence supply hypotheses and priorities. Feedback is saved as a signal for subsequent research.

Map Solidity projects with ilold

ilold is an optional source-code mapper for Solidity projects using the Foundry toolchain. Its project, map, and dependency-graph output seeds hypotheses for verification against the target source.

Prove each finding against the target

The target source plus observed test results or evidence from the source-code structure supports a finding. Hypatia validates report state, structure, and links. Final security judgment stays grounded in source-backed, reviewed evidence.