This release is a pre-release and may not be stable for production use.
Mallace
Mallace has real scoped assessment and verified remediation CLI paths. The shipped API container and sample environment select simulation; broader coverage and production acceptance remain unfinished. See live versus simulation for the tested boundaries and actual AWS/GitHub/provider evidence.
Mallace is a customer-controlled security assessment and remediation prototype for explicitly authorized systems. It includes AI campaigns, scoped repository secret/Python scanners, independent confirmation, and policy-bound issue/patch/PR workflows. Assessment and remediation run through the CLI; the campaign engine also provides FastAPI, a durable queue/ledger and an operator workspace. Bounded real provider-to-PR and AWS S3 acceptance have passed. A full live AI campaign and production release remain unvalidated.
Claude owns frontend work, including the website under site/. The bundled operator
workspace under mallace/api/operator/ is part of the testing product; backend work owns its APIs and package delivery.
Registered maintenance APIs now queue the same real repository and S3 checks under private administrator scopes. Source jobs cover the existing six adapters, keep findings unverified until independent confirmation, and supervise cancellation and owned-container cleanup. See repository jobs and the API contract. Claude owns frontend integration.
The local setup CLI, mallace targets add|list|remove,
creates explicit private repository scopes and registry entries. It starts no scan or
model request; authenticated maintenance jobs remain a separate action.
The installable alpha wheel provides mallace assess, mallace remediate, mallace campaign, mallace serve and mallace targets. See customer installation for the verified artifact workflow and current limits.
Install and verify
Mallace is an alpha CLI for customer-controlled runners. Public releases use:
pipx install mallace
mallace --version
mallace assess --help
mallace targets --help
mallace remediate doctor --help
The first public release is being prepared; the package name does not resolve
until the PyPI upload completes. Before publication, a verified wheel can be
installed with pipx install /absolute/path/to/mallace-VERSION-py3-none-any.whl.
See public release delivery for current
publication status and the tested candidate. Installation needs Python >=3.12;
Git, Docker and pinned scanner images are separate prerequisites for the relevant
assessment and isolated repair adapters.
The available command families are assess, targets, remediate, campaign,
serve and secrets. Installation starts no scan or service. There is no hosted
customer account pairing yet: the website's mallace login and
mallace runner start flow is still unfinished. Existing real CLI assessment and
policy-controlled remediation work independently of that future hosted flow.
For development from a trusted checkout, the validated environment is Linux with Python 3.15.2. Compatibility evidence is recorded in the release documentation.
python3.15 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.lock.txt
scripts/check-local.sh
requirements.lock.txt contains exact runtime versions;
requirements-dev.lock.txt adds pytest and test-only dependencies. These are
version snapshots, not hash-verified supply-chain locks. Node.js is required
for the operator JavaScript checks. Set MALLACE_PYTHON to check another
Python environment. The combined check runs pip consistency, Python tests,
operator syntax, and deterministic operator request-race tests.
A second clean environment installed the snapshots and passed the then-current 94 tests. Later verification and remaining warnings are recorded in Project Status and the delivery ledger.
Explore a simulation
.venv/bin/python main.py --mock
This simulates the provider and target. It does not assess any real product.
Reports are generated as JSON, HTML and SARIF under reports/. Mock mode is
explicit in exports. Generated audit logs and databases can contain sensitive
evidence; review them before sharing. Mock integration tests use temporary
output directories and fake network boundaries.
Supported CLI flags are --mock, --serve, --host, --port,
--target-name, and --target-endpoint. There is no --resume command.
CLI campaigns now use the same lifecycle/case ledger and exclusive ownership
lock. Stop the API using that ledger before launching a standalone CLI campaign.
Local API and operator workspace
Runner settings come from process environment variables by default. To use a trusted dotenv file, select it explicitly with an absolute path, for example MALLACE_ENV_FILE=/secure/mallace.env python main.py --serve. Keep it outside assessed source. A working-directory .env is not loaded automatically.
Set API_ACCESS_KEY to an operator-chosen secret through the process environment or an explicitly selected runner configuration,
then start the local simulated API:
.venv/bin/python main.py --serve --mock
The default bind address is 127.0.0.1:8000. Open /operator for the initial
workspace or /docs for the interactive API reference. Campaign data routes
require Authorization: Bearer <operator-key>. An empty configured key disables
campaign access with HTTP 503; invalid credentials receive HTTP 401.
The workspace can launch mock-only simulations, request cancellation, list actual persisted campaigns, inspect report snapshots, and record review decisions. Live launch remains an advanced API workflow. The simulation form pins expected_mode to mock. It holds the access key only in page memory and clears it on disconnect/reload. Its browser visual verification is outstanding because the browser host was unavailable; HTTP, syntax, and deterministic race checks have been exercised.
Campaign API
POST /campaigns: persist a campaign and return HTTP 202 promptly with its campaign ID and queued status. Poll the status route for execution results. Request body containstargetand an enumeratedscope. Internal campaign tokens are not returned.GET /campaigns?limit=25&offset=0: bounded campaign listing.GET /campaigns/{id}: durable lifecycle status, mode, error code and case counts.GET /campaigns/{id}/cases?limit=25&offset=0: safe journal metadata; no raw bodies or request fingerprints. Pending delivery remains indeterminate.GET /campaigns/{id}/report: protected persisted report snapshot.POST /campaigns/{id}/cancel: cooperative cancellation. It stops future node/case work; it cannot undo an in-flight request.POST /campaigns/{id}/review: recordacknowledgedorrejectedwith a non-empty rationale. This assesses evidence, not remediation, and never resumes requests. One shared operator identity is recorded for this prototype.GET /campaigns/{id}/review: persisted review decision.GET /health: unauthenticated basic health and execution mode.
For retry-safe launches, supply Idempotency-Key (1–128 characters). The same
key and request/configuration return the original campaign rather than execute
again. Changed requests return HTTP 409. Omitting the key creates a new campaign.
Keys and records persist in CAMPAIGN_LEDGER_PATH (default campaigns.db).
Run one API process per ledger on Linux. A file lock prevents a second owner.
On startup, unfinished running/cancelling records become interrupted, never
silently restarted. Unstarted queued jobs survive restarts and execute only if
the configuration fingerprint still matches; changed configuration produces
failed status with configuration_changed. Pending case attempts require reconciliation: target-side
side effects may have happened even if no response was recorded. The case
journal is not durable graph recovery or a guarantee of exactly-once delivery.
Live execution boundaries
Live testing requires explicit target-owner authorization and defined scope. No endpoint is approved by default. The operator must configure:
APPROVED_TARGET_ENDPOINTS: JSON list of exact approved endpoint strings.TARGET_APPROVAL_EXPIRIES: JSON mapping from each endpoint to a future, timezone-aware expiry timestamp.TARGET_NETWORKS: JSON mapping from exact endpoints to explicitly approved CIDR lists. Every resolved address must be permitted; connections pin a literal IP while preserving the original Host/TLS identity. Invalid CIDRs fail startup.- Appropriate provider credentials and models, independently of target approval.
MAX_CAMPAIGN_REQUESTS(default 1000) andEXECUTION_RATE_LIMIT_MS(default 500), according to the authorized scope and traffic budget.
Approval is checked at API intake and before each target request. Target
requests do not follow redirects, inherit environment proxies, or forward
internal campaign tokens. Transport/HTTP failures become failed UNKNOWN cases;
failed/skipped cases are not judged or ranked as vulnerabilities. Invalid live
judge or generator output fails explicitly. Expired or ambiguous grants deny
execution. These controls do not establish target ownership or production security. Target bearer credentials may be configured through the operator-only
TARGET_AUTH_TOKENS JSON mapping from exact endpoint to token. They are kept
separate from campaign authorization; secret-manager integration is unfinished.
Current limits
The operator key is not multi-user identity or tenant isolation. Distributed scheduling, safe graph resume, complete per-case recovery, a reviewed live evaluation benchmark, independently validated drift methodology, general secret detection, retention/off-host restore drills and production monitoring remain unfinished. Reports are evidence for review, not security certifications. Autonomous remediation is being implemented in Mallace using ForgeLoop principles; ForgeLoop itself remains unchanged. Customer acceptance and the remaining release gates are still open.
Read HANDOFF.md, the roadmap,
and Product Status for implementation evidence
and open gates. The historical prototype README is archived under
docs/reference/Prototype-README-history.md; its capability claims are historical,
not current operator instructions.
Local workers are bounded by MAX_CONCURRENT_CAMPAIGNS (default one); the
waiting queue is bounded by MAX_QUEUED_CAMPAIGNS (default 20). A full queue
returns HTTP 429 before creating a campaign. Existing-key retries return their
original record. Queued cancellation stops the job before execution. Shutdown
marks active jobs interrupted and waits for workers before releasing ownership.
Provider calls have PROVIDER_TIMEOUT_SECONDS (default 60), no SDK retries,
and AutoGen has an overall EXPLORATION_TIMEOUT_SECONDS (default 120).
See local operations for cancellation,
snapshots, restoration and local container instructions.
Drift comparisons require observed baseline classifications, unique matched case IDs, identical prompts, matching mode/configuration and sufficient reviewed observations. Legacy desired refusal labels cannot establish drift. Review flags/context supplied by the caller are metadata, not independently verified provenance; see drift evidence.
GitHub/Vercel publication is now authorized. The private full product repository
is JRH89/mallace; Vercel builds site/ from
main. See deployment setup.
Autonomous assessment/remediation is now an active workstream. The first customer runner slice provides trusted policy validation, durable issue delivery, isolated patch/review/retest and verified PR delivery with opt-in merge. A real bounded scanner/model repair test opened a verified private fixture PR; see live acceptance evidence. Customer infrastructure, opt-in merge and operational release gates remain open.
For scoped offline secret-pattern assessment of committed source, see Offline Assessment. This executes locally and reports unverified observations with explicit coverage.
An opt-in sandboxed Gitleaks adapter adds the pinned tool’s built-in secret rules with explicit scope, release verification and container isolation.
Independent confirmation connects a live observation to a trusted exact-finding probe before remediation eligibility.
Offline Python code assessment runs five review patterns with pinned Semgrep, complete reported target accounting and unverified findings.
Offline Dockerfile assessment adds pinned no-network Trivy checks with exact target accounting and source suppression rejection. Local runner secrets explains desktop keyring storage and private credential loading.
Offline Kubernetes manifest assessment checks committed Pod/Deployment YAML with no cluster access, explicit grants and exact file accounting. Real cloud configuration scanning is being added with explicit account/bucket grants and disposable live acceptance.
Offline dependency advisory assessment checks declared exact Python pins against a trusted hash-pinned database without installs or customer inventory uploads. Explicit prepare-db handles supplier data separately from network-disabled scans.
Real AWS S3 configuration assessment reads explicitly scoped bucket configuration without object access or writes; account setup and actual bucket acceptance are tracked separately.
Cloud-to-source repair maps fresh scoped S3 observations to explicitly authorized CloudFormation JSON and runs independent source confirmation plus the real issue/patch/review/retest/PR pipeline. Actual private cloud-source PR acceptance passed; PRs do not deploy cloud changes.
Metadata
Release files for mallace 0.1.0a14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mallace-0.1.0a14-py3-none-any.whl | Python 3 | none | any | Details for mallace-0.1.0a14-py3-none-any.whl |
Release files / mallace-0.1.0a14-py3-none-any.whl
| Download URL | mallace-0.1.0a14-py3-none-any.whl |
|---|---|
| Size | 227.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ffc944712eab6a1093cbcb70943da2f48763d6aefb76b215bcf3461dda5bc9a5
|
|
BLAKE2b-256 checksum How to use checksums |
8e866f6e0be5af827cc600a1950969fe216aae73f5f2e5bda42eef5e8143d760
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for mallace 0.1.0a14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
1 file in this release has been uploaded with provenance metadata.
Attestation for mallace-0.1.0a14-py3-none-any.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.