Metadata-Version: 2.4
Name: mallace
Version: 0.1.0a34
Summary: Customer-controlled authorized security assessment and verified remediation
License-Expression: BUSL-1.1 AND MIT
Project-URL: Homepage, https://mallace.codefrontlabs.com
Project-URL: Repository, https://github.com/JRH89/mallace
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles==25.1.0
Requires-Dist: annotated-doc==0.0.5
Requires-Dist: annotated-types==0.8.0
Requires-Dist: anyio==4.16.0
Requires-Dist: autogen-agentchat==0.7.5
Requires-Dist: autogen-core==0.7.5
Requires-Dist: autogen-ext==0.7.5
Requires-Dist: certifi==2026.10.23
Requires-Dist: charset-normalizer==3.5.2
Requires-Dist: click==8.5.0
Requires-Dist: distro==1.9.0
Requires-Dist: fastapi==0.162.0
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpcore2==2.16.0
Requires-Dist: httpx==0.28.1
Requires-Dist: httpx2==2.16.0
Requires-Dist: idna==3.20
Requires-Dist: Jinja2==3.1.6
Requires-Dist: jiter==0.18.0
Requires-Dist: jsonpatch==1.42
Requires-Dist: jsonpointer==3.8
Requires-Dist: jsonref==1.1.0
Requires-Dist: langchain==1.4.9
Requires-Dist: langchain-core==1.7.6
Requires-Dist: langchain-openai==1.7.4
Requires-Dist: langchain-protocol==0.0.20
Requires-Dist: langgraph==1.2.19
Requires-Dist: langgraph-checkpoint==4.3.1
Requires-Dist: langgraph-prebuilt==1.1.1
Requires-Dist: langgraph-sdk==0.4.12
Requires-Dist: langsmith==0.14.17
Requires-Dist: MarkupSafe==3.0.4
Requires-Dist: numpy==2.5.4
Requires-Dist: openai==3.46.0
Requires-Dist: opentelemetry-api==1.45.2
Requires-Dist: orjson==3.13.0
Requires-Dist: ormsgpack==1.13.0
Requires-Dist: packaging==26.3
Requires-Dist: pillow==13.0.0
Requires-Dist: prometheus_client==0.26.0
Requires-Dist: protobuf==5.29.6
Requires-Dist: psycopg2-binary==2.9.13
Requires-Dist: pyautogen==0.10.0
Requires-Dist: pydantic==2.14.2
Requires-Dist: pydantic-settings==2.16.2
Requires-Dist: pydantic_core==2.50.2
Requires-Dist: Pygments==2.21.0
Requires-Dist: python-dotenv==1.2.4
Requires-Dist: PyYAML==6.0.3
Requires-Dist: redis==8.1.0
Requires-Dist: regex==2026.9.29
Requires-Dist: requests==2.34.2
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: scipy==1.18.1
Requires-Dist: sniffio==1.3.1
Requires-Dist: starlette==1.10.0
Requires-Dist: tenacity==9.2.1
Requires-Dist: tiktoken==0.14.0
Requires-Dist: truststore==0.10.5
Requires-Dist: typing-inspection==0.4.5
Requires-Dist: typing_extensions==4.16.0
Requires-Dist: urllib3==2.8.0
Requires-Dist: uuid_utils==0.19.0
Requires-Dist: uvicorn==0.54.0
Requires-Dist: websockets==17.4
Requires-Dist: xxhash==4.0.2
Requires-Dist: zstandard==0.25.0
Requires-Dist: boto3==1.43.125
Requires-Dist: botocore==1.43.125
Requires-Dist: jmespath==1.1.0
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: s3transfer==0.19.3
Requires-Dist: six==1.17.0
Requires-Dist: awscrt==0.38.0
Requires-Dist: cffi==2.1.1
Requires-Dist: cryptography==50.0.2
Requires-Dist: pycparser==3.12
Dynamic: license-file

# Mallace

Mallace finds serious security bugs in your GitHub repositories, proves each one with a
regression test that fails on your current code, fixes it, has an independent model
review the fix, and opens one pull request per verified fix. Nothing merges automatically.
Scanning is free. Website: <https://mallace.codefrontlabs.com>.

Current release: **0.1.0a34** on [PyPI](https://pypi.org/project/mallace/) and in the
[GitHub Action](https://github.com/JRH89/mallace-action) (`JRH89/mallace-action@v0`).
Mallace is alpha software.

## What it finds

Proved and fixed with pull requests (24 rules across Python, JavaScript/TypeScript, PHP,
Ruby and Go, including Django, Flask, FastAPI, Express, Next.js, Laravel, WordPress and Rails):

- SQL injection
- Command injection
- Code injection (`eval`, plus `exec` in Python and `instance_eval`/`class_eval` in Ruby)
- Template injection (Go templates parsed from caller input)
- Cross-site scripting: request data sent back as HTML unescaped (Python and JavaScript/TypeScript)
- Server-side request forgery: the server fetching a URL taken from the request (Python and JavaScript/TypeScript)
- Unsafe deserialization (`yaml.load`, `pickle`, PHP `unserialize`, Ruby `Marshal.load` and unsafe YAML)

Java is scanned for SQL injection, command injection and unsafe deserialization; Java findings
are reported but not fixed yet.

Reported on every scan, without fixing:

- Leaked secrets: API keys and private keys committed to the repository (the key is never printed)
- Vulnerable dependencies: exact versions in `requirements*.txt`, `package-lock.json`,
  `composer.lock` and `Gemfile.lock`, checked against the public [OSV](https://osv.dev) database

`mallace attack` starts your web app from the pushed code in a Docker sandbox with no network, attacks
that copy over HTTP, and reports only attacks a planted canary proved: SQL, command, code and template
injection, file reads outside the app, and cross-site scripting. It never touches a deployed site. It
reports; it doesn't fix yet. Apps that need a database server or other service to start can't run in
the sandbox yet.

Separately, `mallace site` runs a read-only security check on a live website you have
proved you own with a DNS record, file or meta tag. It looks; it doesn't attack.

## How a run works

1. **Scan**: a pinned, offline Semgrep ruleset runs on your runner and lists suspected bugs.
2. **Prove**: a model writes a regression test, run in a sandbox with no network. It must
   fail on your current code, or Mallace leaves the code alone.
3. **Fix**: a model writes the smallest fix. The same test must pass and the code must compile.
4. **Review**: a second, independent model reviews the change. A rejected fix goes back
   with the reviewer's feedback.
5. **Deliver**: one issue and one pull request per verified fix, with the test that proved it.

Scanning and tests run on your runner. To write a test, fix or review, only the code
around that finding is sent to the Mallace service, which passes it to the model for that
call and does not store it.

## Use it

Three ways, all using the same license key:

- **The app**: sign in with GitHub at <https://mallace.codefrontlabs.com/app>.
- **The GitHub Action**: add `JRH89/mallace-action@v0` to a workflow:

  ```yaml
  permissions:
    contents: write
    issues: write
    pull-requests: write
  jobs:
    mallace:
      runs-on: ubuntu-latest
      timeout-minutes: 60
      steps:
        - uses: actions/checkout@v4
        - uses: JRH89/mallace-action@v0
          with:
            license-key: ${{ secrets.MALLACE_LICENSE }}
            budget: '2'   # most the AI may spend per run, in dollars
  ```

- **The CLI** (Python 3.12 or later; Docker for the test sandbox):

  ```sh
  pipx install --pip-args=--pre mallace   # or: pip install --pre mallace
  mallace doctor            # checks Docker, your license and GitHub login
  mallace fix --scan-only   # free: list suspected bugs
  mallace activate          # paste your license key once
  mallace fix --budget 5    # prove, fix and open PRs
  ```

  Website check:

  ```sh
  mallace site verify example.com   # shows how to prove you own it, then confirms the proof
  mallace site check example.com    # read-only check with a plain-English report
  ```

Full documentation: <https://mallace.codefrontlabs.com/docs>.

### CLI commands

| Command | Purpose |
|---|---|
| `fix` | Find, prove, fix and open PRs for this repository (`--scan-only` for a free scan) |
| `doctor` | Check this machine and repository are ready for `mallace fix` |
| `activate`, `license` | Store, inspect or remove the license key used for fixes |
| `config` | Saved defaults for `mallace fix` |
| `site` | Read-only checks of a website you own |
| `login`, `connection` | Personal identity, runner enrollment and owner-requested runner jobs |
| `assess`, `targets`, `runner` | Scoped offline assessment and local runner commands (advanced) |
| `remediate` | Policy-controlled remediation pipeline (advanced) |
| `campaign`, `serve`, `secrets` | AI red-team campaigns, the local API and runner secrets (advanced) |

## License

Releases from 0.1.0a27 are licensed under the [Business Source License 1.1](LICENSE),
with an additional use grant to scan code and to generate fixes with a Mallace license
key. The Change Date is 2030-11-08, when it converts to Apache 2.0, as stated in `LICENSE`. Earlier releases and inherited
prototype code are under the [MIT License](LICENSE-MIT).

## Development

Mallace evolved from the `AI-Product-Red-Team-Agent` prototype. The installed
find-and-fix, website and hosted identity/enrollment paths have passed live acceptance;
the shipped API container and sample environment select simulation for AI campaigns.
See [live versus simulation](docs/planning/Live-vs-Simulation.md) and
[Project Status](docs/planning/Project%20Status.md) for tested boundaries and evidence.
Claude owns frontend work, including the website under `site/`; backend work owns the
APIs, the bundled operator workspace APIs and package delivery.

For development from a trusted checkout, the validated environment is Linux with
Python 3.15.2. Compatibility evidence is recorded in the release documentation.

```bash
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](docs/planning/Project%20Status.md) and the
[delivery ledger](docs/superpowers/plans/2026-11-04-mallace-delivery.md).

## Explore a simulation

```bash
.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:

```bash
.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 contains `target` and an
  enumerated `scope`. 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`: record `acknowledged` or `rejected` with 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) and `EXECUTION_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 the [roadmap](docs/planning/Production%20Roadmap.md),
and [Product Status](docs/planning/Project%20Status.md) 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](docs/planning/Local-Operations.md) 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](docs/planning/Drift-Evidence.md).

The private product repository is [JRH89/mallace](https://github.com/JRH89/mallace);
Vercel builds the website in `site/` from `main`. See [deployment setup](docs/planning/GitHub-Vercel-Deployment.md).

Autonomous assessment/remediation is now an active workstream. The first
[customer runner slice](docs/planning/Autonomous-Remediation.md) 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](docs/planning/First-Live-Repair.md).
Customer infrastructure, opt-in merge and operational release gates remain open.

For scoped offline secret-pattern assessment of committed source, see [Offline Assessment](docs/planning/Offline-Assessment.md). This executes locally and reports unverified observations with explicit coverage.

An opt-in [sandboxed Gitleaks adapter](docs/planning/Gitleaks-Assessment.md) adds the pinned tool’s built-in secret rules with explicit scope, release verification and container isolation.

[Independent confirmation](docs/planning/Independent-Confirmation.md) connects a live observation to a trusted exact-finding probe before remediation eligibility.

[Offline code assessment](docs/planning/Semgrep-Assessment.md) runs Mallace's pinned Semgrep rules with complete reported target accounting and unverified findings.

[Offline Dockerfile assessment](docs/planning/Trivy-Assessment.md) adds pinned no-network Trivy checks with exact target accounting and source suppression rejection. [Local runner secrets](docs/planning/Local-Secrets.md) explains desktop keyring storage and private credential loading.

[Offline Kubernetes manifest assessment](docs/planning/Kubernetes-Assessment.md) 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](docs/planning/Dependency-Assessment.md) 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](docs/planning/AWS-S3-Assessment.md) reads explicitly scoped bucket configuration without object access or writes; account setup and actual bucket acceptance are tracked separately.

[Cloud-to-source repair](docs/planning/Cloud-Source-Repair.md) 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.

[Standalone local runner](docs/planning/Local-Runner-CLI.md) adds explicit foreground
assessment execution, durable local submissions, inspection and cancellation.
[Hosted identity and enrollment](docs/planning/Hosted-Identity-and-Enrollment.md) and
[outbound runner jobs](docs/planning/Outbound-Runner-Jobs.md) connect a local runner to the hosted service.
