Read Me First — Dependency Security Auditor

Welcome. This page is for someone meeting this project for the very first time. It explains, in plain language, who the product is for, what it does, the world it operates in, and how to get started — with pointers to the more detailed guides when you need them. No technical background is assumed.

1. Who this is for

The Dependency Security Auditor is built for the people responsible for keeping software safe and compliant:

• Application-security engineers — the specialists who must find and fix security weaknesses across many software projects at once.
• Platform and DevOps teams — the people who run the machinery that builds and ships software, and who want unsafe changes stopped automatically.
• Open-source maintainers — volunteers and small teams who need a no-cost way to check the components their project depends on.
• Legal and compliance officers — the people who must produce evidence (increasingly demanded by regulators and customers) of exactly what a piece of software contains.

If you are any of these — or you manage people who are — this product is for you.

2. What it does

Modern software is mostly assembled, not written from scratch: a typical application reuses hundreds of ready-made building blocks ("dependencies") published by other people. Any of those blocks can carry a publicly known security flaw, and a few are outright malicious.

The Dependency Security Auditor:

1. Finds every building block a software project uses — including the ones pulled in indirectly — across seven of the most common programming ecosystems.
2. Checks each one against public databases of known security flaws, and also looks for signs a package is malicious or impersonating a trusted one.
3. Ranks what it finds by genuine risk, so the handful of issues worth acting on rise above the wall of theoretical ones. Every ranking shows its reasoning — nothing is a black box.
4. Stops risky software from shipping when you want it to, by failing an automated build that crosses a risk threshold you set.
5. Produces the compliance paperwork — a machine-readable inventory of every component (called an SBOM) in the two accepted industry standards.
6. Proposes fixes — including, when an AI service is configured, suggested code changes delivered as review requests. Proposals are always reviewed by a human; the product never merges a change on its own, and anything AI-generated is clearly labelled as such.

You can use it three ways: as a command-line tool on your own machine (no account needed), as a shared service with a web dashboard for a whole organization, or from inside the Visual Studio Code editor via its extension.

3. The domain: software supply-chain security

The field this product lives in is called software composition analysis, part of the wider discipline of software supply-chain security.

The background, briefly: because software is assembled from public, reusable components, an application inherits the flaws of everything it includes. Those flaws are catalogued publicly (each gets an identifier, such as a "CVE number") so defenders can react — but the same catalogues tell attackers exactly where to strike. Separately, criminals now publish deliberately harmful packages with names one typo away from popular ones, hoping a developer installs the wrong one.

The industry's chronic problem is noise: traditional checkers report every theoretical match, producing thousands of alerts of which only a handful are real, exploitable risks. Teams drown, alerts get ignored, and the one that mattered slips through. This product's whole design philosophy is to separate the signal from that noise — and to show its working when it does.

4. Where it fits

The auditor sits alongside the tools a software team already uses:

• Code-hosting services (GitHub, GitLab, Bitbucket) — it can fetch a project directly from these to scan it, and it delivers proposed fixes back to them as ordinary review requests.
• Build pipelines ("CI/CD" — the automation that tests and ships code) — the scanner runs as a pipeline step and can fail the build when risk is too high. Its reports use a standard format that security dashboards ingest.
• Public vulnerability databases — the sources of truth about known flaws; the auditor consults them and caches what it learns.
• Your organization's sign-in service — the shared service and dashboard delegate login to the platform's central identity provider, so people sign in once with their normal account; there are no separate passwords to manage.
• An AI service (optional) — only the differentiating extras (suggested code fixes, writing policies in plain English, deeper "is this flaw actually reachable?" analysis) use one; all core scanning and ranking works without it.

Expected customers range from a single developer running the free command-line tool, to organizations running the shared service for many teams and projects.

5. First run

The quickest way to see the product working is the preview: a single self-contained package (a Docker container) that runs the entire product on your own machine, pre-loaded with realistic sample data. Start it, wait about a minute, and open the dashboard in your web browser. The preview guide in the project's preview folder gives the exact steps.

One thing to know: the preview asks you to sign in, exactly as the real product does. Because the preview is not connected to a real sign-in service, the guide describes an evaluation-only switch that lets you in as a sample administrator. That switch is off unless you deliberately turn it on, and it cannot be enabled in any real deployment.

Once in, start at the Overview page — it summarises the sample organization's risk at a glance — then click into a project to see its findings ranked by real risk.

6. Setting up

To move from looking at the preview to auditing your own software, an organization typically does these things (each covered in the detailed guides):

1. Deploy the service (or have your platform team do it) and connect it to your organization's sign-in service — see the deployment guide.
2. Prepare the production database for first use with the guarded initialization tool — see the production-initialization guide.
3. Connect your code repositories, either by pointing scans at a project's address or by saving a repository connection with its access credential, so private projects can be scanned too.
4. Add the scanner to your build pipeline, so every change is checked automatically and risky ones are blocked.
5. Set your policies — the rules that define what your organization tolerates (administrators can write these in plain English when an AI service is configured; they are always shown for review before use).
6. Optionally install the editor extension, so developers see problems while they code — see the extension user guide.

7. Day to day

A normal rhythm once running:

• Scans happen continuously — triggered by the build pipeline, from the dashboard's "New scan" page (any signed-in member can start one), from the command line, or from the editor.
• Someone reviews the top findings — the ranked list makes this a minutes-not-hours job. Each finding explains which component, which flaw, the evidence, and why it ranked where it did. When the tool cannot tell whether a flaw is actually reachable in your code, it says "undetermined" honestly rather than guessing.
• Fixes get applied — usually by moving to the fixed version the finding names; where fix proposals are enabled, a ready-made review request appears in your code-hosting service for a human to approve. Nothing merges itself.
• Policy violations get attention — the dashboard shows where the organization's own rules are being broken.
• Compliance artefacts on demand — an up-to-date component inventory (SBOM) can be produced whenever a customer or regulator asks.

8. Ongoing care

• Keep scanning regularly. New flaws are published every day against components that haven't changed — yesterday's clean scan can be today's critical finding. Scheduled or per-change scans in the pipeline handle this.
• Vulnerability data refreshes itself as scans run; no manual feed maintenance is needed.
• Review open fix proposals periodically so they don't go stale.
• Back up the service's database on your normal operations schedule (the service stores findings, policies, and history there; the deployment guide covers where it lives).
• Revisit policies occasionally — thresholds that suited last year may be too loose or too strict today.

Glossary

Term	Plain meaning
Dependency	A ready-made software building block your project reuses. Most arrive indirectly, pulled in by other blocks ("transitive").
Vulnerability / CVE	A publicly disclosed security flaw; each gets a catalogue number like CVE-2019-10744.
SBOM	"Software Bill of Materials" — a complete, machine-readable ingredients list for a piece of software.
Reachability	Whether your code actually touches the flawed part of a component. Many reported flaws are never reachable.
Supply-chain attack	Compromising software by corrupting one of its building blocks — e.g. publishing a malicious look-alike package.
CI/CD pipeline	The automation that builds, tests, and ships code whenever it changes.
Policy	A rule your organization sets about what risk is acceptable (e.g. "no critical flaws in anything customer-facing").
Fix PR	A proposed code change ("pull request") delivered to your code-hosting service for human review.
Organization	The top-level boundary in the shared service: its projects, people, findings, and policies are isolated from every other organization's.

The other documents

All in this user-docs folder:

Document	What it's for
getting-started.md	Trying the tool hands-on — command line and service, with exact commands.
dashboard.md	A tour of every dashboard screen and what you can do on each.
api-reference.md + openapi.yaml	The service's HTTP interface, for people integrating other systems with it.
remote-scan-source.md	How the service scans projects delivered remotely (uploads or repository addresses), and the safety limits around that.
supply-chain-detection.md	How malicious and impersonating packages are detected, beyond known-flaw matching.
deployment.md	How the service is deployed and how to prove a running deployment is healthy.
production-initialization.md	Preparing a brand-new production database for first use.
demo-data.md	Loading the realistic sample data used for demos and screenshots.
useful-commands.md	The day-to-day commands for developers working on this product itself.
testing.md	What the product is tested for, in plain terms, with the full test list.
vsc-extension-userguide.md	Using the Visual Studio Code editor extension.

User roles

The shared service has two levels of access. Administrators manage policies (creating, enabling, disabling) and other administrative actions. Members — everyone else who is signed in — can view everything and start scans. Nobody, at any level, can make the product merge a code change or silently alter a finding: fixes are proposals, and findings state their evidence.

Sample data, and starting fresh

The preview ships pre-loaded with a realistic sample organization: five projects, their dependencies, findings across every severity, policies, and example fix proposals — so every screen has something to show. It is sample data only. To start fresh, simply start a new preview container: the data resets to the same sample set every time. (Teams running the real service load or clear the same sample data with the seeding tool described in demo-data.md; it never touches real records.)

Common questions

• The preview's sign-in page never lets me in. Expected: the preview has no real sign-in service attached. Use the evaluation-only switch described in the preview guide.
• A finding says reachability is "undetermined". Is that a bug? No — it is the product being honest that it could not establish reachability with confidence, rather than guessing either way.
• Will it change my code by itself? Never. Fixes arrive as review requests; a human always decides.
• Does scanning send my source code anywhere? The command-line tool scans entirely on your machine. When the shared service scans an upload or fetches a repository, it examines the files and then discards them — it keeps the findings, not your source, and it never executes your code.
• Why did a project that scanned clean last month show findings today? New flaws are disclosed daily. The component didn't change; the world's knowledge of it did.

Where to get help

Questions, feedback, and discussion happen in the wbsp.ai community — see wbsp.ai. The documents above answer the how-to questions; the community is the place for everything else.