Repository navigation
1.0.0 — 2026-04-14
First tagged release under the clearwing name. Covers the full
Phase 0–6 refactor that took the project from "works on my machine"
to a shippable release: rebrand from vulnexploit, shim demolition,
Finding-type unification, tools reorganization, graph hardening, full
CI gate, release-hygiene scaffolding, and MkDocs documentation site.
Added
- Release hygiene scaffolding:
SECURITY.mdresponsible-disclosure
policy,CONTRIBUTING.mddev-setup and PR-checklist guide,
CHANGELOG.md(this file),py.typedPEP 561 marker so downstream
consumers get Clearwing's type information,dependabot.ymlfor
pip + GitHub Actions (grouped weekly updates),.github/ISSUE_TEMPLATE/
bug and feature templates with security-lane routing. - Docs site (MkDocs Material):
docs/index.md,docs/quickstart.md,
docs/architecture.md,docs/cli.md,docs/api.md(mkdocstrings
autogen),docs/openglass.md(the Overwing design deep dive). Built
withmkdocs build --strict, deployed to GitHub Pages via a paths-
filter-gated workflow. uv.lock— 4446-line lockfile pinning 154 packages against
Python 3.12 for bit-for-bit reproducible dev environments via
uv sync --all-extras.Makefilewithtest / lint / type / build / clean / install-dev / gate / all / docs / docs-servetargets that mirror the CI gate
exactly.make gateis the local mirror.clearwing/capabilities.py— runtime detection of optional
subsystems (guardrails, memory, telemetry, events, audit, knowledge)
exposed as acapabilities.has(name)API. Replaces six
try/except ImportErrorblocks inclearwing/agent/graph.py.tests/test_tool_registry.py— snapshot test locking
get_all_tools()at 63 tools with stable names and no duplicates,
so tool reorgs can't silently drop coverage.LICENSEfile at the repo root (the project was MIT-declared in
pyproject.tomlbut missing the file).
Changed
- Package rebranded from
vulnexploittoclearwing. The
on-disk package, PyPI name, CLI command, logger names, DB/log
file names, config paths, and GitHub repo URL all flipped in one
atomic commit. Existing~/.vulnexploit/state on user machines
will NOT carry over — Clearwing reads from~/.clearwing/and
treats the old path as absent. Back up first if you need the old
state. The new canonical remote is
git@github.com:Lazarus-AI/clearwing.git. - Finding types unified. The sourcehunt
SourceFindingTypedDict
is gone, replaced by theclearwing.findings.Findingdataclass
used across network and source-hunt pipelines. Two unrelated
Findingclasses renamed to eliminate the collision:
clearwing/analysis/source_analyzer.py::Finding→AnalyzerFinding,
clearwing/safety/scoring/dedup.py::Finding→DedupRecord. A
transitional dict-style access shim on theFindingdataclass
(__getitem__,__setitem__,get(),__contains__) keeps test
fixtures that use dict literals working. clearwing/agent/tools/reorganized into seven domain
subdirectories:scan/,exploit/,hunt/,recon/,ops/,
data/,meta/. The top-level__init__.pyis now a pure
aggregator.get_all_tools()still returns the same 63 tools in
the same order.clearwing/agent/tools/hunt/hunter_tools.py(791-LOC god file)
split into four focused files underhunt/:sandbox.py
(HunterContext+ variant routing, 105 LOC),discovery.py(4
read-only FS probes, 226 LOC),analysis.py(4 sandboxed
build/execute tools, 435 LOC),reporting.py(record_finding,
85 LOC). Largest file in the subpackage is now 435 LOC, down from
791. Thehunt/__init__.pyaggregator composes the four builders
in the original tool order so the tool-registry snapshot stays
green.graph.pyhardened: sixtry/except ImportErrorblocks that
storedNoneon failure replaced with unconditional imports plus
acapabilities.has(name)gate. Static analysis tools now see
real symbols instead ofOptional[None]fallbacks.- CI gate expanded:
ruff check,ruff format --check, scoped
mypy (findings + sourcehunt + capabilities + agent/tools + core),
pytest -q --strict-markers --strict-config,python -m build,
twine check— all six steps run on every push/PR across Python
3.10, 3.11, 3.12. - Typed-core policy:
disallow_untyped_defs = true+
warn_unused_ignores = trueenforced onclearwing.findings.*,
clearwing.capabilities,clearwing.sourcehunt.*,
clearwing.agent.tools.*, andclearwing.core.*— 68 source files
at zero mypy errors. No# type: ignore[no-untyped-def]
suppressions; every annotation is real. - README trimmed from 508 → 139 lines. Tagline, install,
quickstart, architecture diagram, docs table, reporting lanes,
license. Full detail moved todocs/. - All 22 deprecated shim packages deleted (
vulnexploit.scanners,
vulnexploit.exploiters,vulnexploit.payloads, and 19 others).
Canonical paths underclearwing.scanning.*,
clearwing.exploitation.*, etc. are the only way to import these
modules. ADeprecationWarning-as-error filter inconftest.py
locks the trunk against accidental re-introduction.
Fixed
ChatAnthropic(model=model)→ChatAnthropic(model_name=model)
inclearwing/sourcehunt/runner.py::_build_llm_from_model_string.
Themodel=kwarg was removed in recentlangchain-anthropic; the
old call site would have raisedTypeErroron first use of
--model <name>on the sourcehunt CLI.- Variable-shadowing type confusion in
sourcehunt/runner.py
wherefor f in files(a FileTarget loop) leaked its narrowing
into laterfor f in all_findings(a Finding loop). Loop variables
renamed to disambiguate. _walk_ast_for_taintsignature insourcehunt/taint.pyfalsely
claimedsource_text: strwhen the caller passed raw bytes on
purpose (for tree-sitter byte offsets under multi-byte UTF-8 source).
Signature now honestly declaresbytes | str.- Evidence-ladder threshold types:
adversarial_threshold,
PATCH_GATE, andmin_evidence_levelacrossverifier.py,
patcher.py,disclosure.py, andrunner.pyare now typed as
theEvidenceLevelLiteral[...]instead of plainstr. - Implicit Optional cleanup: 23
param: X = Nonesites across
core/*,agent/tools/*converted toparam: X | None = None
(mypy'sno_implicit_optionaldefault). Paired with 5 real
arg-type mismatch fixes (ports or [],credentials or {},
payload or "",wordlist or [],options or {}) where the
downstream API required non-None. EventBus._handlers/_lockinstance attributes — the
singleton stores them via__new__, which mypy doesn't pick up
without explicit class-level declarations. Added them.dynamic_tool_creator.pyimportlib.util.spec_from_file_location()
returnsModuleSpec | None; added a guard that short-circuits to
a structured failure response if the spec/loader are None instead
of crashing onmodule_from_spec().browser_tools.py_browser_statetyped asdict[str, Any]
with a localbrowser =binding in_ensure_browserso the
chained.new_context(...)call type-checks.- Python 3.10–3.12
NameErrorin
clearwing/scanning/os_scanner.pyfrom a bareexceptpattern
that 3.13 tolerated but earlier versions didn't. - 225 tracked
__pycache__files removed from git. A new
.gitignorekeeps them out for good. - Build backend in
pyproject.tomlfixed from the hallucinated
setuptools.backends._legacy:_Backendto the real
setuptools.build_meta.python -m buildnow produces a valid
wheel + sdist.
Removed
vulnexploitpackage, CLI, module, and every reference. See
theChangedsection for migration notes.hunter_tools.py(the 791-LOC god file) deleted in favor of
thehunt/{sandbox,discovery,analysis,reporting}.pysplit..reference/dangling gitlinks — 5 submodule pointers
(cai, shannon, pentagi, PentestGPT, strix) that were started as
submodules but never wired up with.gitmodulesor
.git/modules/. Dropped from the index withgit rm --cachedin
a normal commit (no history rewrite was needed — the 857 MB lived
in the operator's working tree, not in git history). Operators can
still clone external projects into.reference/<name>locally;
.gitignorecovers the path.