LLM安全评估框架

Prerequisites

• Python >= 3.9
• Node.js >= 18 (for frontend)
• Git

Web dashboard + WebScan 依赖

pip install -e ".[web]"

全量依赖

pip install -e ".[all]"

Installation

```bash

Setup Dev Environment

pip install -e ".[dev]"
cd frontend && npm install

Build Frontend

cd frontend
npm run dev                       # Dev server with hot reload
npm run build                     # Production build → dist/

---

快速开始

前置要求

• Python >= 3.9
• Node.js >= 18，只有运行前端时需要
• Git

安装

```bash git clone https://github.com/Coff0xc/LLM-Security-Assessment-Framework.git cd LLM-Security-Assessment-Framework

后端最小安装

pip install -e .

Quick Start

usage-pricing-catalog.yml

models: mock:test-model: prompt_usd_per_1k_tokens: 0.01 completion_usd_per_1k_tokens: 0.02 source: example-provider-pricing-sheet

For repeatable report reruns, suites can write and replay model responses from
a local JSON cache. Cache keys are derived from the model name and prompt
SHA256, so raw prompt bodies are not stored in the cache file. Cached entries do
store model outputs and usage metadata, so treat the cache as restricted report
evidence. Paths are resolved relative to the suite YAML file. Pair the cache
with `random_seed` when you want repeated evolutionary prompts to replay
deterministically across CLI runs.

Reports include a Response Cache section with hits, misses, stored entries, and
whether the cache file was updated during the run.

Suites can import MCP server/tool manifests and turn each tool description into
a deterministic report case. The importer recursively reads `tools` arrays from
JSON or YAML manifests, names cases as `mcp-tool-*`, and keeps the manifest
source visible in report scope and `suite-config.json`. Imported cases also
carry structured provenance metadata (`source_type`, `manifest_file`,
`tool_name`, server trust fields, annotation keys, annotation hashes, and
`description_sha256`) in `suite-cases.jsonl` and `suite-case-matrix.csv`.
Nested MCP `annotations` fields are included in the normalized tool text so
malicious metadata buried under schemas or metadata blocks is still reportable.
Each imported MCP case also carries a heuristic `server_trust_score`, and the
Markdown/HTML report includes an MCP Trust Summary with tier counts, highest
score, affected cases, server names, and the score model rationale used to
interpret each tier.

MCP manifests can also be gated by server trust tier. When
`allowed_mcp_trust_tiers` is configured, imported MCP cases with missing or
unapproved `server.trust.tier` metadata become policy violations while the run
still writes the full report pack for reviewer evidence.

MCP trust scores and rationale can be calibrated with a local JSON/YAML policy
file. The policy file is included in Source Inventory with SHA256 and byte size,
and the custom score model flows into case metadata plus the MCP Trust Summary.

使用截图

下面的截图来自 examples/ready-for-handoff-suite.yml 生成的真实报告交付链路，展示当前项目最核心的报告包、QA 回执和归档校验能力。

报告包总览

QA 交接回执

归档校验

Screenshots

The screenshots below are generated from examples/ready-for-handoff-suite.yml and show the repository's current report-delivery workflow.

Configuration

```bash cp .env.example .env

Edit .env with your API keys (optional — mock mode works without any keys)

```

Option 1: generate a ready-for-handoff report pack

forgedan suite preflight examples/ready-for-handoff-suite.yml --strict --output reports/preflight-ready forgedan suite run examples/ready-for-handoff-suite.yml --output reports/suite-ready forgedan suite validate-report reports/suite-ready/suite-result.json forgedan suite verify-bundle reports/suite-ready/suite-manifest.json forgedan suite qa-report reports/suite-ready/suite-manifest.json --output reports/suite-ready/qa --strict-handoff forgedan suite archive reports/suite-ready/suite-manifest.json --output reports/suite-ready/handoff.zip forgedan suite verify-archive reports/suite-ready/handoff.zip

Option 2: CLI attack demo (zero config, mock mode)

forgedan run --quick -g "test prompt" -m mock:test

Option 3: Web Dashboard

forgedan web # Backend at :5000 cd frontend && npm run dev # Frontend at :5173 → open http://localhost:5173

Option 4: Python API

python -c " from forgedan import ForgeDAN_Engine, ForgeDanConfig from forgedan.adapters import ModelAdapterFactory

adapter = ModelAdapterFactory.create_from_string('mock:test-model') engine = ForgeDAN_Engine(ForgeDanConfig(max_iterations=3, population_size=3)) engine.set_target_llm(adapter.generate_sync) result = engine.run('{goal}', 'test goal', 'target output') print(f'Success: {result.success}, Fitness: {result.best_fitness:.4f}') " ```

The first command sequence is the recommended smoke path for this repository: it runs the no-model preflight, generates a complete report pack, validates the machine-readable artifacts, checks manifest integrity, writes a QA receipt, and packages the deliverable into a ZIP that can be verified after handoff.

---

CLI Reference

forgedan run -g "goal" -m "provider:model"   # Run attack
forgedan run --quick -g "goal"                # Quick demo (3 iterations)
forgedan test -m "provider:model"             # Test model connectivity
forgedan suite run examples/smoke-suite.yml   # Run a reproducible YAML suite with prompt/response scans
forgedan suite run examples/smoke-suite.yml --run-id-dir # Archive under output/<run_id> to avoid overwrites
forgedan suite run examples/agent-tool-suite.yml # Generate an Agent/MCP/RAG report pack
forgedan suite run examples/tool-policy-suite.yml # Generate an expected policy-fail tool-policy pack
forgedan suite run examples/mcp-manifest-suite.yml # Import MCP tool metadata into report cases
forgedan suite run examples/mcp-trust-policy-suite.yml # Generate an expected policy-fail MCP trust pack
forgedan suite run examples/mcp-trust-calibrated-suite.yml # Apply a local MCP trust score policy file
forgedan suite run examples/model-artifact-suite.yml # Import local model artifacts into report evidence
forgedan suite run examples/model-serialization-suite.yml # Scan local model serialization files without loading them
forgedan suite run examples/coverage-policy-suite.yml # Enforce required coverage gates
forgedan suite run examples/duplicate-evidence-suite.yml # Demonstrate duplicate evidence grouping
forgedan suite run examples/report-metadata-suite.yml # Generate a report with formal assessment metadata
forgedan suite run examples/acceptance-criteria-suite.yml # Add report acceptance criteria/sign-off gates
forgedan suite run examples/ready-for-handoff-suite.yml # Generate a fully passing report handoff sample
forgedan suite run examples/review-decision-suite.yml # Document accepted risk / reviewer decisions
forgedan suite run examples/risk-register-owner-suite.yml # Pre-fill risk register owner/status/due date
forgedan suite run examples/cost-pricing-suite.yml # Estimate report usage cost from suite pricing inputs
forgedan suite run examples/custom-scorer-suite.yml # Run a suite-defined reusable contains scorer
forgedan suite run examples/cached-response-suite.yml # Replay repeat report runs from a local response cache
forgedan suite preflight examples/ready-for-handoff-suite.yml --output reports/preflight # Check report readiness before model execution
forgedan suite compare base.json curr.json    # Compare two suite-result.json artifacts
forgedan suite taxonomy --json                # Export report finding taxonomy
forgedan suite schemas --json                 # Export report artifact schema references
forgedan suite validate-report suite-result.json # Validate a report artifact contract
forgedan suite verify-bundle suite-manifest.json # Verify report pack checksums and schemas
forgedan suite archive suite-manifest.json --output handoff.zip # Zip a verified report or comparison pack
forgedan suite verify-archive handoff.zip # Verify archive checksums, schemas, and suite cross-artifact consistency
forgedan suite qa-report suite-manifest.json  # Write JSON/Markdown QA handoff receipt
forgedan suite qa-report suite-manifest.json --strict-handoff # Fail when readiness is not passed
forgedan report --input logs/attacks/          # Generate report
forgedan web                                  # Launch web dashboard
forgedan defense generate --input logs/        # Generate defense training data
forgedan info                                 # Show framework info
forgedan distributed coordinator              # Start distributed coordinator

Before spending time or provider budget on a report run, `forgedan suite preflight <suite.yml>` performs a no-model readiness audit. It checks that the suite has formal report metadata, handoff acceptance criteria, risk-register owner/due-date defaults, policy/coverage gates, deterministic replay controls, valid scorer names, source inventory provenance, MCP trust policy when MCP manifests are imported, and an explicit model-serialization scope note when heuristic artifact scanning is used. Add --output <dir> to write suite-preflight.json and suite-preflight.md; suite run also includes the same preflight artifacts in every generated report pack. The JSON artifact is covered by schemas/suite-preflight.schema.json and can be validated with forgedan suite validate-report <dir>/suite-preflight.json. The command exits non-zero only for failed checks by default; add --strict to also fail on review_required items, or --json to print the audit for CI/archive scripts.

Suites can keep cases inline or load a reusable case file:

cases_file: examples/cases/prompt-injection-mini.jsonl
scorers:
  - target_prefix
  - refusal
  - response_safety

Suites can also define lightweight reusable deterministic scorers. A contains scorer records whether the model response includes required reviewer-facing text and stores the scorer output in each case result, the case matrix, and score summary.

scorers:
  - refusal_phrase_present
scorer_definitions:
  - name: refusal_phrase_present
    type: contains
    text: cannot help

When a suite imports cases_file, mcp_manifest_file, or model_artifact_files, reports include a Source Inventory section with each input path, SHA256, byte size, and generated case count. The same inventory is stored in suite-config.json for audit replay and handoff checks, and the report schemas require it in both suite-config.json and the embedded suite-result.json configuration snapshot. validate-report also checks that the report Source Inventory counts match its entries and that the embedded suite configuration snapshot matches the report section.

Suites can include formal report metadata for assessment handoff. These fields flow into suite-config.json, suite-result.json, and the Markdown/HTML report metadata section. The public redacted report replaces client, author, and reviewer names with stable placeholders.

report_metadata:
  assessment_id: LLM-REPORT-001
  report_title: LLM Security Assessment Report
  client: Example Corp
  authors:
    - Security Assessment Team
  reviewers:
    - Report QA Lead
  classification: Confidential
  assessment_start: "2026-05-01"
  assessment_end: "2026-05-31"

Suites can also define report acceptance criteria for QA and sign-off workflows. Each item is carried into suite-config.json, suite-result.json, Markdown/HTML reports, and the QA receipt. A failed item blocks ready_for_handoff, while review_required keeps the acceptance section visible without marking the bundle as fully accepted. Acceptance criteria whose IDs match handoff checklist items, such as residual-risk-owner-signoff, raw-artifact-handling, and limitations-reviewed, can also turn those QA receipt items from review_required into passed when the criterion is marked passed or accepted_risk.

acceptance_criteria:
  - id: evidence-reviewed
    title: Evidence matrix reviewed
    status: passed
    owner: QA Lead
    evidence: suite-evidence.csv
    notes: Evidence rows sampled against the Markdown report.
  - id: residual-risk-owner-signoff
    title: Residual risk owner sign-off complete
    status: review_required
    owner: Risk Owner
    evidence: suite-risk-register.json
    notes: Awaiting final residual risk owner approval.
  - id: raw-artifact-handling
    title: Raw artifact handling reviewed
    status: passed
    owner: QA Lead
    evidence: Raw prompts and responses restricted to authorized reviewers.
  - id: limitations-reviewed
    title: Limitations reviewed
    status: passed
    owner: QA Lead
    evidence: Report limitations match the scoped assessment.

Policy failures can be paired with reviewer decisions without changing policy_passed. This gives the report pack a decision log for accepted risk, approvals, required mitigations, or rejected exceptions, and the QA receipt records whether policy exceptions have documented decisions.

review_decisions:
  - id: accept-demo-residual-risk
    title: Accept demo residual risk for report pack
    status: accepted_risk
    owner: QA Lead
    related_policy_violations:
      - max_risk_score
    related_cases:
      - injection-case
    evidence: Assessment owner accepted this residual risk for a controlled report demo.
    notes: Re-review before external publication.

Risk registers can be pre-filled with suite-level remediation tracking defaults. These values flow into suite-risk-register.json and suite-risk-register.csv for each generated finding, so the report pack can be handed to the owner without manually editing blank tracking columns first.

risk_register_defaults:
  owner: AppSec Team
  status: open
  due_date: "2026-06-30"

Suites can include externally maintained model pricing inputs for reproducible usage cost estimates. ForgeDAN does not fetch live prices; the report records the source string you provide and computes estimated_cost_usd from observed prompt and completion tokens. You can keep rates inline, or point the suite at a local JSON/YAML pricing catalog. Catalog files are included in Source Inventory with SHA256 and size metadata so report reviewers can audit the price source used for cost calculations.

usage_pricing:
  prompt_usd_per_1k_tokens: 0.01
  completion_usd_per_1k_tokens: 0.02
  source: pricing-sheet-v1

usage_pricing_file: usage-pricing-catalog.yml

```yaml

API Endpoints

<details> <summary><b>REST API reference (click to expand)</b></summary>

```

攻击方法

Report Workflow

1. Define scope in a suite YAML file: cases, imported evidence sources, report metadata, policy gates, coverage requirements, acceptance criteria, reviewer decisions, and risk-register defaults.
2. Run preflight with forgedan suite preflight to catch missing metadata, weak handoff criteria, unresolved scorer names, missing provenance, and incomplete deterministic replay settings before spending provider budget.
3. Generate the report pack with forgedan suite run; the run writes raw and redacted machine-readable artifacts, Markdown/HTML reports, CSV matrices, coverage, risk register, release notes, and a manifest.
4. Validate locally with forgedan suite validate-report and forgedan suite verify-bundle; these checks bind schemas, hashes, summary counts, redacted artifacts, Markdown/HTML sidecars, and cross-artifact identities back to the source result.
5. Prepare handoff with forgedan suite qa-report --strict-handoff; the receipt records checklist status, blockers, acceptance criteria, source inventory, schema checks, and reviewer-facing evidence.
6. Archive and verify with forgedan suite archive and forgedan suite verify-archive; generated release notes and the full report bundle index carry these handoff commands, and verify-bundle checks that they stay present. The same archive flow supports normal suite report packs and historical comparison packs.

模型适配器

QA Receipt