PhantomGuard - Anti-Hallucination Git Hook

PhantomGuard version
PhantomGuard status
PhantomGuard cache
PhantomGuard install (no foreign hook)
PhantomGuard install (foreign hook)
PhantomGuard help
PhantomGuard scan /path
PhantomGuard scan all --strict (Unknown -> Phantom)
PhantomGuard scan staged
PhantomGuard Fix
PhantomGuard scan all
PhantomGuard TUI Structure

Inspiration

The original proposition was made by Christos who had simply heard about this emerging cybersecurity topic and thought it was an interesting project. After our team completed our brainstorming session, we voted on which idea to pursue, and this was chosen by the majority. We were inspired to build PhantomGuard out of the need for a definitive, local guardrail that prevents these phantom dependencies from ever crossing the commit boundary.

What it does

PhantomGuard is a deterministic, terminal-first dependency verifier and Git pre-commit hook. It statically analyzes Python, JavaScript/TypeScript, and Go files to extract dependency candidates without executing the repository's code. It queries public registries (PyPI and npm) to verify existence; if a package returns a 404, it is flagged as a phantom and the commit is blocked. It also features a local typosquat engine to flag suspicious names and an optional AI advisor for explanations.

How we built it:

Building PhantomGuard was a collaborative team effort, and we used ChatGPT extensively throughout both the building and debugging phases.

Architecture & Drafting: Thanasis created the first draft, which Christos then modified and created the version we began on the project on and hevily relied on it. Then the project emerged to a more structured and robust approach as we progressed through it.

Core Engineering: Panagiotis started the heavy building phase and created a really strong base. Christos helped and Vaggelis tested the software from the begging of it till the end and Mishe created the frontend and connected it to the backend.

Security & AI: Vaggelis & Panagiotis added security patches and tested the application, Thanasis added the AI features, and Christos added the provenance checks and stricter blocking logic.

Polish: Finally, Panagiotis, Christos and Vaggelis polished the project and created a compiled executable complete with icons for Linux, Windows and MacOS.

Some of the challenges we had to overcome are:

Guaranteeing deterministic outcomes required strict handling of network uncertainty. Timeouts and DNS failures cannot be assumed safe, so we engineered the system to flag them as "unknown" and block them in strict mode. Static extraction also posed challenges with arbitrary dynamic imports, forcing us to block them entirely in strict mode since they cannot be resolved without code execution. Furthermore, securely integrating the optional AI advisor required strict isolation so that credentials are never stored in the repository and the AI never influences the security verdict.

Accomplishments that we're proud of

We are immensely proud of the sheer hard work, intense collaboration, and late-night debugging our team poured into bringing PhantomGuard to life, successfully shipping a secure, zero-execution static analysis tool that integrates flawlessly into developer workflows. We take particular pride into building our highly polished, responsive terminal workspace (TUI) and robust CLI that adapts seamlessly to any terminal width or environment. Through relentless teamwork, we successfully engineered native, cross-platform release archives for Linux, MacOS, and Windows complete with custom application icons, while implementing advanced backend features like strict provenance checks, rigorous blocking rules, and a process-safe local cache utilizing atomic replacements to guarantee complete data integrity during concurrent hook and CI executions.

What we learned

We learned that the local commit boundary is the most effective bottleneck for preventing supply-chain pollution before it reaches production. Working as a team highlighted how effectively AI tools like ChatGPT can accelerate complex building and debugging. We also recognized the importance of local provenance on requiring both go.mod and go.sum evidence, to strictly enforce package integrity. But regardless of the technical skill that we gained during this hackathon, we learned from our collaboration is that with the right team and good core idea we can achieve much more than we expect and that is our most important asset.

What's next for PhantomGuard - Anti-Hallucination Git Hook

Moving forward, we aim to expand our static analysis capabilities to support additional languages and package managers, such as Rust, Java, and C/C++, which are currently out of scope. We will also continue refining our extraction engines to handle complex ecosystem edge cases while strictly maintaining our zero-execution security guarantees.