Metadata-Version: 2.4
Name: langchain-darkmoon
Version: 0.1.0
Summary: LangChain tools for Darkmoon, the local privacy-first autonomous AI penetration testing engine.
Author: ASC-IT (Darkmoon)
License: MIT
Project-URL: Homepage, https://github.com/ASCIT31/Dark-Moon
Project-URL: Source, https://github.com/ASCIT31/langchain-darkmoon
Project-URL: Issues, https://github.com/ASCIT31/langchain-darkmoon/issues
Keywords: langchain,darkmoon,pentest,security,dast,appsec,vulnerability,ai-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core<0.4,>=0.3
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# langchain-darkmoon

[![Darkmoon](https://img.shields.io/badge/Darkmoon-autonomous%20pentest-4f46e5)](https://github.com/ASCIT31/Dark-Moon)
[![Star Dark-Moon on GitHub](https://img.shields.io/github/stars/ASCIT31/Dark-Moon?style=social)](https://github.com/ASCIT31/Dark-Moon)

LangChain tools for **[Darkmoon](https://github.com/ASCIT31/Dark-Moon)**, the local, privacy first autonomous AI penetration testing engine. Give a LangChain agent the ability to **trigger a Darkmoon pentest against a target you are authorised to assess, pull back the findings, and review the fix pull requests Darkmoon prepares**, over your own self-hosted Darkmoon Dashboard API.

> Darkmoon runs and validates security tests. It does not, and these tools do not, guarantee that a system is secure. Findings can include false positives and must be reviewed by a qualified human. Only run assessments against systems you own or have explicit written authorisation to test. These tools never merge a pull request; every fix is left for a person to review and merge.

## Install

```bash
pip install langchain-darkmoon
```

(Until it is on PyPI, install from source: `pip install .` in a clone of this repository.)

## Tools

| Tool | Purpose |
| --- | --- |
| `DarkmoonRunPentestTool` | Start a campaign against an authorised target; optionally wait and return findings and severity stats. |
| `DarkmoonGetFindingsTool` | Return the vulnerabilities and aggregated stats for a campaign id. |
| `DarkmoonListCampaignsTool` | List the campaigns visible to the authenticated dashboard user. |
| `DarkmoonListPullRequestsTool` | List the fix pull requests Darkmoon prepared (read only), optionally scoped and filtered by state. |

`DarkmoonToolkit` bundles all four with one shared connection.

## Connection

Darkmoon is self hosted, so you point the tools at your own **Darkmoon Dashboard API** (the FastAPI service shipped with Darkmoon, typically on port `8000`). There is no public endpoint. The tools log in with `POST /api/v1/auth/login` to obtain a short lived JWT.

```python
from langchain_darkmoon import DarkmoonToolkit

toolkit = DarkmoonToolkit(
    base_url="http://darkmoon.internal:8000",
    username="analyst",
    password="...",  # or wire from your secret store
)
tools = toolkit.get_tools()

# Bind to any tool-calling LLM / agent:
# from langchain.agents import create_agent
# agent = create_agent(model, tools)
```

Or use a single tool directly:

```python
from langchain_darkmoon import DarkmoonRunPentestTool

pentest = DarkmoonRunPentestTool(
    base_url="http://darkmoon.internal:8000", username="analyst", password="..."
)
result = pentest.invoke({"target": "https://staging.example.test", "wait_for_completion": True})
print(result["total"], "findings")
```

## Remediation and secrets (Pro)

Remediation is optional and is a paid Darkmoon **Pro** feature. The open source Darkmoon focuses on finding, proving and reporting findings locally; the feature that prepares fix pull requests is Pro. When enabled it needs a **credential reference**, an opaque id of a credential stored in Darkmoon's encrypted vault (created in the dashboard), not a raw token. Raw source control secrets never travel through these tools, and the remediation agent only ever prepares a pull request for human review; it never merges. `DarkmoonListPullRequestsTool` can **read** those pull requests through the API regardless of edition.

## Privacy

Darkmoon keeps assessment work on your own infrastructure and applies a privacy gateway so the language model works over placeholders rather than your real hosts, IPs and credentials. These tools send data only to the base URL you configure.

## Development

```bash
pip install -e ".[test]"
pytest -q
```

The API client (`langchain_darkmoon/client.py`) is dependency free and transport injected, so its logic and the tool wrappers are unit tested without a network (mock transport). A full end to end run additionally requires a running Darkmoon instance pointed at an authorised target.

## Related integrations

Darkmoon also ships maintained integrations for [n8n](https://github.com/ASCIT31/n8n-nodes-darkmoon), [Activepieces](https://github.com/ASCIT31/activepieces-piece-darkmoon), [Dify](https://github.com/ASCIT31/dify-plugin-darkmoon) and [GitHub Actions](https://github.com/ASCIT31/darkmoon-scan-action).

## License

MIT, see [LICENSE](./LICENSE). Not affiliated with LangChain; "LangChain" is a trademark of its respective owner.
