OASIS audits code with local models and a deterministic verdict on every finding

What the tool actually is

OASIS stands for Open Automated Security Intelligence Scanner, and the project describes itself as an AI powered security auditing tool that uses local LLMs, either Ollama or any OpenAI compatible server such as vLLM, LiteLLM or LM Studio, to detect and analyse potential security vulnerabilities in your code. The point of running models locally is that the code under review never leaves your machine, which matters for a scanner pointed at proprietary source. The project is written in Python, requires Python 3.9 or newer, is licensed GPL-3.0-only, and is published on PyPI as the package oasis with a single console entry point declared as oasis = "oasis:main". The repository root is compact and tells you how the thing is laid out, with oasis.py at the top, an oasis/ package, a vulnerability/ directory, a scripts/ directory, a tests/ directory, a test_files/ directory that appears to hold sample code, and agent and editor instruction files in .agents/ and .cursor/. The version is 0.7.0, released on 2026-09-09, with 0.6.1 and 0.6.0 earlier in 2026, and the repository is not archived. The framing throughout is assistant rather than enforcement, and that is the honest expectation to set.

One pipeline with named phases

The orchestration is described as a single LangGraph pipeline, with the phase sequence given as discover, then scan, then expand, then deep, then verify, then report, plus an optional proof of concept assist step, and bounded retries on context expansion. Reading that sequence tells you what the tool does better than any feature list. Discover finds the code worth reading. Scan is the cheap first pass over it. Expand grows the context around what the scan found, with a bound on how many times it will retry, which is the difference between a scanner that hangs and one that gives up. Deep is the expensive second phase where stronger models look properly. Verify checks the results. Report turns the whole thing into output. The two phase design is offered explicitly as a way to use lightweight models for the initial scanning and stronger ones for deep analysis, and the pipeline also supports parallel processing for vulnerability analysis. The dependency list supports the claim that this is a real pipeline rather than a prompt wrapper, with langchain-core and langgraph pinned as the orchestration layer, ollama for the local model client, pydantic for validation of the structured data that passes between phases, httpx for outbound calls, tqdm for progress, numpy for the numeric work, and packaging for version comparison.

The finding validation agent is the part that matters

Findings are validated automatically during the scan, and this is the most distinctive feature in the project. The validation is described as a deterministic, code driven investigation that looks at entry points, call chains, taint flows and on path mitigations, and it embeds an exploitability verdict with a confidence score in every report, shown as colour coded badges. The guardrails are stated too, which is unusual and welcome. The dashboard assistant can expose the full evidence for a finding, either through a single finding picker or through the Ask AI buttons in the detailed analysis section, and a manual POST to /api/assistant/investigate endpoint allows re-validation with an optional language model narrative, and that narrative is constrained to stay consistent with the deterministic result. So the architecture is that the deterministic pass decides and the language model explains, not the other way round. This matters because the failure mode of language model security review is a confident, plausible and wrong finding, and a system that produces a reasoned verdict with a confidence value is easier to triage than a wall of prose. It also narrows the model down to narration, where it is strong, rather than judgement, where it is not.

Reports, exports and the dashboard

Output is structured rather than printed. The project produces canonical JSON reports plus derived HTML, PDF and Markdown exports, with the canonical JSON holding overview key performance indicators, tier context and similarity highlights, and the HTML matching the dashboard and modal with a table of contents, anchors and charts. Generation of that executive summary starts during the scan and updates as phases complete, which the project calls live progress, so a long run shows something useful rather than a blank terminal. Reports are written under a security_reports/ directory, organised by a project slug, with the canonical JSON as the source of truth from which the other formats are derived. The PDF path is why weasyprint is a dependency, and the HTML path is why jinja2 and beautifulsoup4 are. The web interface is started with the --web flag and has a security section of its own, and the dashboard assistant triages either a single vulnerability JSON report or an executive scan wide mode over the aggregated JSON under the run, with optional retrieval over the local embedding cache, a chat model selector using Ollama tags, Markdown replies, and chat sessions persisted and keyed by the canonical report path. The web and assistant options can be tuned through flags including --web-ollama-url, --web-embed-model and --web-assistant-rag.

Audit mode, diffing, suppressions and inline markers

Several features exist to make the tool usable inside a team rather than as a one off script. Audit mode runs an embedding based similarity audit before a full scan, and if JSON is among your output formats you also get an audit_report.json and Markdown version carrying the same facts, which the dashboard reads for comparison tables and an HTML preview. Scan diffing takes a baseline with the --diff-against option and classifies findings as new, fixed or persistent, which is how you make a scanner argument to a team that already has findings it does not want to churn on. The suppression registry is a fingerprint based list of known issues, and it produces SARIF suppressions and candidates, so a finding you have accepted can be recorded rather than re-argued each run. Inline markers are supported as well, with #oasisignore and #noqa style comments in the source that are dropped before the reports are generated, so a developer can silence a specific line locally. Two phase scanning and scan result caching with model specific caching round it out, alongside the dual layer cache for embeddings and analysis results that the project credits with dramatically speeding up repeated scans. Model selection is guided and interactive, with parameter based filtering, and the command line accepts the web and assistant options, and a streaming mode.

Running it locally and in containers

The dependency set includes the pieces you would expect for a reporting tool with a web dashboard: flask and flask-socketio for the server and its live updates, weasyprint for PDF output, markdown for the Markdown export, numpy and fonttools for the numeric and font work, and beautifulsoup4 for HTML parsing. There is an optional dev extra with coverage. For container use, the compose file offers two arrangements. The typical one runs the CLI against a repository mounted at /work and talks to Ollama running on the host, which the comments spell out exactly:\n\n```yaml\n# docker compose run --rm oasis -i /work/test_files -ol http://host.docker.internal:11434\n```\n\nThe alternative starts a bundled Ollama through the ollama profile and points the scanner at it instead. The services block shows how little is involved:\n\n```yaml\nservices:\n oasis:\n build: .\n entrypoint: [\"oasis\"]\n command: [\"--help\"]\n working_dir: /work\n volumes:\n - .:/work\n extra_hosts:\n - \"host.docker.internal:host-gateway\"\n stdin_open: true\n tty: true\n```\n\nThe image is a slim Debian base with a pinned patch version, and it installs the system libraries that WeasyPrint needs for rendering, which is the part most likely to surprise you:\n\n```dockerfile\nFROM debian:13.4-slim\n\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n git curl \\\n python3 python3-pip python3-venv \\\n pipx \\\n libpango-1.0-0 libharfbuzz0 libpangoft2-1.0-0 libcairo2 \\\n libgdk-pixbuf-2.0-0 shared-mime-info fonts-dejavu-core \\\n && rm -rf /var/lib/apt/lists/*\n```\n\nThe image runs as a non root appuser, installs the project with pipx in editable mode, and deliberately sets no ENTRYPOINT so that a plain docker run with bash does not invoke the scanner, while compose sets the entrypoint to oasis with a default command of --help. The container can also serve the web dashboard, with a command that publishes port 5000 and listens on all interfaces. For continuous integration there is a --fail-on gate with defined exit codes and a GitHub Actions example in the documentation, which is the piece that turns a scanner into something a team actually enforces.

Where the limits are

Three boundaries are worth naming. First, the findings come from a language model. The deterministic validation agent makes them far more trustworthy, and it can even rule a finding down, but it judges exploitability from the code it can see rather than proving a vulnerability, so a green badge is not a security guarantee and a tool that produces findings nobody reads has no value. Second, the tool is bound by what your local models can do. The project encourages using lightweight models for scanning and stronger ones for deep analysis, and that is a genuine quality and cost trade, but a small local model on modest hardware will produce a weaker report than a large hosted model, and the tool gives you no way around that. Third, the licence is GPL-3.0-only, which matters if you intend to fold OASIS into a proprietary product or an internal tool that you distribute, because the obligations attach to derived works rather than to a separate process talking to it over a socket. The project also runs on whatever Ollama or OpenAI compatible server you point it at, which is genuine flexibility, but it also means the quality of the output is a property of your infrastructure rather than of the project, and you should evaluate it with your own models and your own code before committing to it.

Editorial conclusion

Adopt OASIS if you want a security review that runs entirely on machines you control, with a repeatable pipeline, machine readable reports in several formats, and a per finding verdict that tells you which findings are worth a human look. Do not adopt it as a replacement for a human security review or a static analyser, since the findings originate from a language model and the deterministic pass judges exploitability rather than proving a vulnerability. Before you rely on it, read the Finding Validation Principle section, confirm the models you pick are available on your Ollama server, and decide early how you will treat the confidence badges, because a scan that produces no human triage is not an audit.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. psyray/oasis on GitHub
4. README
5. Releases