Ask your agentic AI to run a HAIEC Assurance scan.

How the agent operates HAIEC

A deterministic sequence — the same one every client follows.

1. 1DiscoverPreflight the tenant, AI System, controls, evidence gaps, results, replay status, and any existing investigation.
2. 2InvestigateUse the IDE agent’s permitted local tools; preserve source references, versions, timestamps, hashes, supporting facts, contradictions, and limitations.
3. 3Collect + normalizeChoose an existing supported intake contract; typed profile failures never silently fall back to generic.
4. 4PreviewShow Provided by, Normalized using, destination, case binding, sources, counts, facts, hypotheses, redactions, and limitations.
5. 5Confirm + submitAsk once about that exact batch, then call the canonical intake tool with userConfirmedUpload: true.
6. 6ReceiptReturn producerRunId, accepted/rejected counts, failures, bindings, qualification limits, and what remains unverified.
7. 7Re-evaluateAttach the receipt to a new Evaluation only when requested; historical evaluations never change.
8. 8Explain next actionSeparate HAIEC-established facts, AI interpretation, and the proof boundary or responsible next step.

Re-running the same source analysis does not close a gap that requires policy, IAM, deployment, identity, telemetry, or other external evidence. The agent should follow the deterministic resolution category returned by HAIEC.

Approval contract

Before a supported write, upload, runtime test, source change, or other consequential operation, the agent explains the exact action and asks the user to approve it. For an evidence upload, the agent first shows one readable preview of the exact outbound batch, then asks once; only after the user confirms may it pass userConfirmedUpload: true.

Evidence-upload confirmation authorizes sending that batch to the configured binder. It is not a UCP approval receipt, policy approval, runtime authorization, production-change approval, or proof that a gap is closed.

For this build, user confirmation in the IDE is accepted as the workflow approval signal. This is an execution acknowledgement; it does not independently prove that a production action had path-bound human approval at runtime.

Discovery

Machine-readable entry points:

• /.well-known/haiec-capabilities.json— capability manifest (operations, source modes, statuses).
• /openapi/assurance-v1.yaml— the formal API contract.
• GET /api/v1/systems— runtime discovery of AI Systems (and …/evaluation-sources for verified sources).
• GET /api/v1/evidence/binders— discovery of configured evidence destinations for the intake routes.
• /api/mcp— the HAIEC Assurance MCP server (Streamable HTTP, Bearer API key).

Investigations — start, leave, return

An investigation groups evidence under user-declared states — "first evidence", "before the incident", "after the fix" — so HAIEC can reconstruct what was established at each point. The user never needs HAIEC's internal fields: the agent translates ordinary language into the explicit scenario binding on each ingestion. The IDE agent may inspect permitted local source, configuration, logs, commits, builds, and diagnostics, but its interpretation is not an observed event, HAIEC finding, or Assurance verdict. - "Start a HAIEC investigation" → haiec_preflight, then haiec_scenario_preflight, then haiec_prepare_scenario (one scenarioRunId per investigation; nothing persists until bound evidence exists). - "This is my first evidence" → ingest with the declared first state. - "Here is the next batch" / "start collecting the next state" → haiec_get_scenario_status returns the deterministic next state — never compute ordering from memory or timestamps. - "What changed?" → haiec_reconstruct_scenario and haiec_compare_scenario_states between declared states. - "Continue my HAIEC investigation" (days later, fresh client) → haiec_preflight → haiec_list_investigations → name the found investigation or present the choices, then continue with the exact scenarioRunId. Identity comes from persisted evidence, never conversational memory. - Live capture: haiec_prepare_scenario_capture returns env vars, a scenario-aware OTel Collector config, and test payloads — it persists nothing until you apply it and HAIEC verifies receipt through haiec_get_scenario_status. - Typed evidence: haiec_ingest_structured accepts an intakeProfile (kpi, alarm, api_transaction, policy, and the telecom profiles) that uses the same mapper as the matching REST intake route — you propose the profile from the file shape, the user approves, and a record that fails the typed schema returns the canonical error, never a silent generic fallback. - Large files: split into bounded chunks, keep the same scenario binding on every chunk, use a stable clientBatchKey per chunk (file digest + chunk index), upload in order, and retry only failed chunks — idempotent keys make replays safe. Investigations persist under the AI System's workspace (Investigations tab). An investigation records what evidence arrived and in what declared order — it is not an Assurance disposition. Only a new Evaluation establishes whether anything changed.

The user never needs to know internal identifiers (scenarioRunId, scenarioSequence), level presets (the optional TM Forum AL0/AL1/AL2 vocabulary), or OTLP resource processors — the agent translates “first evidence” and “next batch” into the explicit binding. Persisted investigations are also visible in the AI System workspace under Investigations.

Rules for agents

• Read HAIEC_BASE_URL, HAIEC_API_KEY, HAIEC_AI_SYSTEM_ID, and HAIEC_SOURCE_ASSET_ID from server-side environment or the developer's non-public config.
• Never display, commit, or log the API key. Never use NEXT_PUBLIC_* for it.
• Never send githubToken, X-GitHub-Token, GITHUB_TOKEN, or organizationId to HAIEC.
• Use only configured Source Asset IDs — never a raw repository URL.
• Always send an Idempotency-Key on run creation; poll run status at 15–30s intervals and stop on terminal failure.
• Report exactly what the API returns: run ID, evaluation ID, disposition, what was established, what was not, limitations, report/agent-audit/passport/dashboard links.
• Prefer GET .../agent-audit over the full report for “what did HAIEC prove / what is missing” questions — it carries narrative.established, unestablished, notAssessed, evidenceGaps, and verificationItems[].verificationNeeded verbatim.
• Never manufacture PASS when evidence is missing, partial, or not assessed — and never translate NOT_ASSESSED or UNKNOWN into FAIL.
• Submit evidence only on explicit user request, only through a configured binder, and only via the canonical intake routes. An ingestion receipt means EVIDENCE_INGESTED — never a closed gap; only a new Evaluation establishes change.
• Running a scan never requires code changes; remediation is a separate user decision.

Canonical flow

configured Source Asset
  → POST /api/v1/assurance/runs
  → poll GET /api/v1/assurance/runs/{runId}
  → GET links.summary → GET links.agentAudit
  → GET links.masterReport (bounded) — canonical Master Assurance Report
  → GET links.masterReport?detail=full only when deeper analysis is required
  → links.report / links.pdf remain the secondary Assurance Evidence artifacts
  → open links.dashboard in the HAIEC Dashboard

optional, explicit user request only:
  GET /api/v1/evidence/binders → POST /api/ingest/* or /api/otlp/v1/*
  → attach receipt.producerRunId to a NEW run (producerId: structured-ingress)
  → compare old vs new evaluation facts

Telemetry and evidence ingestion are OPTIONAL — static Assurance needs only the key, AI System, and verified Source Asset. Ready-to-use agent instructions exist per tool: Cursor, Claude Code, Devin, and a generic agent guide for everything else.

When something fails

Translate known error codes into the exact user action. Do not turn optional evidence setup into a global Assurance blocker.

When HAIEC is not connected — local Quick Check

## When the user asks to "run HAIEC" — decision sequence 1. FULL ASSURANCE — HAIEC MCP or API key is configured and reachable: use the normal Assurance workflow (haiec_preflight → haiec_run_assurance → poll → summary → agent audit). 2. SETUP REQUIRED — HAIEC MCP is connected but haiec_preflight reports setup incomplete: explain the exact missing steps from preflight verbatim. If a local repository is available, you may also offer a Quick Check (below) — never in place of completing setup. 3. NO HAIEC CONNECTION — no API key or MCP configured, local repository available: say exactly — "Full HAIEC Assurance is not connected for this repository. I can still run HAIEC's independent local developer-security tools for a preliminary source-security review. These results are not a HAIEC Assurance Evaluation and will not appear in the HAIEC Assurance dashboard." Offer, only with the user's approval before installing or running: - AI AppSec (npx -y ai-appsec) — deterministic static source-security analysis for AI/agent code (requires Semgrep installed separately). - MCP Tenant Isolation (npx -y mcp-tenant-isolation mcp) — only when the repository builds MCP servers or tools. ## Presenting Quick Check results Inspect the repository deeply and propose fixes, but keep three kinds of statements clearly separate: - DETERMINISTIC PACKAGE FINDING — exactly what the scanner reported (rule, file, line). Quote it; never rewrite it as a HAIEC finding. - AI REPOSITORY INTERPRETATION — your reading in this codebase's context (reachability, exploitability, affected paths). - AI RECOMMENDATION — likely remediation and what to verify. Lead with the most important findings first, name the affected files, state the package's limitations, and close with what a full HAIEC Assurance Evaluation could additionally answer (capability and action-path analysis, authority/policy evidence, runtime evidence, Guided Assurance, Agent Audit, Reports, Passport). After the check, say: "These were independent HAIEC developer-security checks performed locally. They do not create a HAIEC Assurance Evaluation and are not stored in your HAIEC Assurance dashboard. Full HAIEC Assurance adds broader capability and action-path analysis, authority and policy evidence, runtime evidence, Guided Assurance, Agent Audit, Reports and Passport." Truth locks: - AI_APPSEC_RESULT != HAIEC_ASSURANCE_EVALUATION - MCP_TENANT_ISOLATION_RESULT != HAIEC_ASSURANCE_EVALUATION - FREE_LOCAL_CHECK != FULL_HAIEC_ASSURANCE - LOCAL_PACKAGE_RESULT != HAIEC_DASHBOARD_EVIDENCE

Try these with your AI

Copy any prompt into your configured agent.

• “Check whether HAIEC is ready to evaluate this system.”
• “Run HAIEC Assurance on the connected source.”
• “Explain my HAIEC result in plain English.”
• “What did HAIEC establish?”
• “What remains unknown or not assessed?”
• “Group the open evidence questions and tell me which ones you can help resolve.”
• “What evidence is missing?”
• “Show me the highest-consequence action paths.”
• “Which capabilities are code-capable but not runtime-observed?”
• “Help me investigate the evidence gap using only the files and diagnostics I authorize.”
• “Show me the exact evidence preview, including who provided it and how it was normalized.”
• “Help me connect the evidence HAIEC says is missing.”
• “Can these logs help close any HAIEC evidence gaps?”
• “Submit these logs to HAIEC and rerun Assurance.”
• “Configure telemetry for this project, but ask before changing my files.”
• “Run the authorized runtime preflight.”
• “Compare this Evaluation with the previous one.”
• “Open the exact HAIEC report for this run.”
• “Start a HAIEC investigation.”
• “This is my first evidence.”
• “Here is the next batch — start collecting the next state.”
• “Continue my HAIEC investigation.”
• “What changed between my first evidence and the latest state?”
• “Where does the proof stop?”