KILLCHAIN: Following Trust Through the Software Supply Chain

This is a submission for the MLH x DEV Writing Challenge.

A Hacktoberfest 2026 adventure: Creating KILLCHAIN.

We use packages every day. A quick npm command. An import statement. We are using someone's code.

The code that lives in a developer's GitHub repository and the package you download from npm are not always the same. Builds can change files. Sometimes unintended changes end up in the published package.

So how do you know that what you are installing is what the developers actually wanted to publish?

At the Hacktoberfest Hack Day in Sonipat we found a problem that asked this question directly. It became KILLCHAIN.

What We Created

KILLCHAIN is a tool that checks whether the published package matches the source code. Enter a package name and a version. KILLCHAIN downloads the published tarball and fetches the matching source from GitHub and tells you if the two are the same.

No it is not a folder comparison. A difference between source and package is not always a problem. Builds can legitimately add bundles, metadata and transformed files. The real challenge is figuring out which of those differences need attention.

A scan gives you:

• 🔍 Package retrieval: downloads the published tarball. Checks the registry's shasum.
• 🛡️ Extraction: unpacks with limits on path traversal, size and file count. Never runs any code.
• 🌐 Source retrieval: finds the GitHub repo and the commit that matches the published version.
• 📄 Manifest and diff: file hashes on both sides, then a list of added, removed and changed files.
• 🧱 Build-artifact classification: expected build output is labeled; unusual files stand out.
• 🚨 Security analysis: suspicious code is marked with severity, evidence and confidence.
• ✍️ Provenance checks: check signatures and attestations that support the source-to-build claim.
• Risk score: SAFE, WARN or CRITICAL with reasons clearly explained.
• 🤖 AI explanation: the findings are turned into sentences that people can understand.
• 🕘 Scan history: past scans are saved in SQLite so you can look at them again.

Why This Idea?

Every dependency is an act of trust. We use packages made by people we do not know and rarely question how the published version was made.

That gap is where supply chain attacks happen. Someone may type a package name wrong. Someone may use a company's package name on the registry. Someone may quietly add something to a release just before it is published.

What drew us in is how common the problem is. We all install packages every day. Almost none of us ever check them.

What Happens When You Hit Scan

1. Download the tarball from the npm registry. Check its shasum against what the registry says.
2. Extract it carefully. There are limits on size and file count. None of the code runs.
3. Find the source: which GitHub repo and which commit matches this version.
4. Hash every file on both sides, compare the lists. Figure out which changes are just part of the build process.
5. Then the security rules run. You get a score and an explanation in words.

The Stack

The frontend is React 19 with TypeScript on Vite. It has a form, a results page with diffs and a findings history view.

The backend is Python, FastAPI and Uvicorn. The whole process is behind three endpoints: start a scan, get the result and list scans.

Scan history is saved in a SQLite file. Using a database server for this felt like overkill.

The extraction and manifest code has unit tests as that is where the worst bugs would be.

Backend is on Render, frontend is on Vercel and GitHub Actions handles tests and deployments.

One thing we debated and got right was the split between analysis and AI explanation. The scanner finds what actually happened and the AI layer only explains it. If a security tool says a package is dangerous you should be able to click on the file that triggered it. Not a feeling.

How the Hackathon Actually Went

We split the work into three parts: the scanning engine, the frontend and deployment and CI. Everything went through PRs, which was a learning experience.

The biggest problem we faced was run.sh. Run.sh often creates merge conflicts. At one point we committed an empty version just to escape the loop, then rebuilt it properly with process cleanup and a cross-platform Python lookup. During that rebuild we also committed pycache to git by mistake, fixed it and later discovered we did the same thing in a second directory. We added pycache to .gitignore. We checked it twice.

Hosting presented its issues. The free tier of Render puts the backend to sleep after a period of inactivity. If you open the app cold the API takes time to respond. Our frontend now tells you that the backend might just be waking up. We learned this by sitting through those cold starts ourselves.

We used AI coding to help a lot for parts of the stack that none of us had worked on before. Scaffolding was where AI coding helped the most; AI coding help could create a FastAPI route or a React component in seconds. Safe extraction was where we were skeptical. The generated archive handling needed corrections for path safety and npm package/ prefix. We only trusted AI coding help after writing tests designed to break it. Generate, question, test. That loop became our process.

What We Learned

• A difference is not a threat. Comparing files is easy. Understanding why they differ is the challenge.
• Findings need proof. A risk label means nothing without the files, changes and reasoning behind it.
• AI does not analyze. Deterministic checks show facts. AI makes them easy to read.
• Working is not the same as understanding. AI makes implementation faster. Debugging and verifying the result is still the job.

What's Next?

KILLCHAIN works with npm today. Next is PyPI support via an ecosystem adapter and release monitoring that rechecks packages when new versions arrive.

Let's Talk!

Every dependency is a little bit of the trust we place in someone's code. When was the last time you checked whether a published package matched its source? Would you run a check like that before your install? Tell us your thoughts. Thanks for reading and happy building! 🚀

Project: KILLCHAIN
Team: SoloLeveling (Darsh Rustagi, Moksh Bansal, Mudit Jindal)
GitHub: https://github.com/darshr25558-pixel/KillChain
Live app: https://kill-chain-node.vercel.app/