Skip to main content

Run HAIEC from Devin

Devin does not need special HAIEC endpoints. It calls the same Assurance API used by every other client. The session uses the HAIEC API key and configured system/source identifiers — GitHub repository credentials stay server-side between HAIEC and the GitHub App.

Prerequisite: the repository is already connected to a HAIEC AI System through the GitHub App and the Source Asset shows CONNECTED + VERIFIED. See the Connected GitHub guide first.

1. Secrets — session or environment only

# .env.local — SERVER_SIDE_ONLY. Must be gitignored.
# Never prefix the API key with NEXT_PUBLIC_.
# Use the "IDE / Agent Full Assurance" purpose for the complete IDE
# workflow (setup + evidence + receipts); "Assurance Agent" remains a
# read/run/evidence-only key.
HAIEC_BASE_URL=https://www.haiec.com
HAIEC_API_KEY=haiec_live_xxx
HAIEC_AI_SYSTEM_ID=SYSTEM_ID
HAIEC_SOURCE_ASSET_ID=VERIFIED_SOURCE_ID
  • Provide these values as Devin session/environment secrets or via a gitignored .env.local — never committed to the repository.
  • Never prefix the key with NEXT_PUBLIC_ and never paste it into a prompt. If a value is missing, the agent should ask rather than guess.

2. Preferred — HAIEC MCP server

Devin supports remote HTTP MCP servers. With HAIEC MCP configured, Devin calls HAIEC tools directly — haiec_run_assurance, haiec_get_agent_audit, and the rest — instead of hand-writing HTTP calls. Same API key, same tenant scope.

// .devin/mcp_config.local.json — gitignored; keep the key out of committed config
// (Devin web UI equivalent: Settings → Custom MCP → HTTP transport → same URL + header)
{
  "mcpServers": {
    "haiec": {
      "url": "https://www.haiec.com/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer <HAIEC_API_KEY from your environment/secret store>"
      }
    }
  }
}

If MCP is configured, prefer the MCP tools (haiec_run_assurance, haiec_get_agent_audit, haiec_list_systems, ...). If only HAIEC_API_KEY is set, use the Assurance REST API v1 below — both surfaces reach the same canonical pipeline with the same tenant and scope enforcement.

HAIEC Assurance MCP (https://www.haiec.com/api/mcp — Streamable HTTP, stateless; protocol 2026-07-28 modern + stateless compatibility for 2025-era clients; Bearer HAIEC_API_KEY, not OAuth). Full IDE evidence journey: DISCOVER → INVESTIGATE → COLLECT → NORMALIZE → PREVIEW → USER CONFIRMS → SUBMIT → RECEIPT → RE-EVALUATE → EXPLAIN. HAIEC determines qualification, evaluation, control state, and proof boundary; the IDE agent is the local investigator and normalizer, not a verdict engine. 1) haiec_preflight — the IDE control plane. Returns tenant identity (org name/ID, key name, scopes — never key material), AI System targets with exact IDs and selectionRequired (multiple systems → ASK the user, never pick by display name), setup checks, and actions marked canExecuteViaIde/browserRequired/confirmationRequired/ recommendedTool. 2) SETUP (ide-full key required — perform only approved actions): - No system → haiec_create_ai_system (userConfirmed). - No GitHub App → haiec_github_preflight gives the installation URL; the user installs in the browser, then you poll to resume. - haiec_list_github_repositories → haiec_bind_github_source (userConfirmed) → verification through the trusted path. - No repo access → haiec_submit_local_scan + haiec_run_assurance attachedScanId (canonical ci-attached). - haiec_list_connectors tells you what is LIVE vs Enterprise POC. - haiec_setup_telemetry (userConfirmed) → binder + OTLP endpoints + collector config template; verify via haiec_get_telemetry_status. - Manual asset registration (haiec_register_asset) is always REGISTERED + NOT_VERIFIED — never claim verification you did not earn. 3) haiec_run_assurance — requires a caller-generated idempotencyKey (UUID per intended run; same key+payload replays, key+changed-payload conflicts). 4) haiec_get_run until evaluation.evaluationId appears. 5) haiec_get_summary. 6) haiec_get_agent_audit — the primary explanation surface. Its resolutionGroups field groups open verificationItems into deterministic resolution groups (verificationNeeded verbatim, affected question/path IDs, resolutionOwner, canIdeHelp, recommendedTool, approvalRequired, browserActionRequired, missingInputs, rerunWillNotResolve). Use it to reduce many open items to a few evidence needs — it never invents requirements or changes any status. For a one-call reading, haiec_explain_evaluation returns the versioned deterministic Report Explanation Packet — identity, verbatim disposition, established/unestablished/notAssessed, bounded verification items (depth "executive" default; "technical"/"auditor" add items, the Four Questions and authority planes), canonical representative receipt state and access-level-tagged artifact links. It composes the same canonical reads — it is an explanation, never a new verdict. 7) haiec_get_report only when deeper analysis is needed. Runtime testing (optional — same canonical owner as the dashboard): - haiec_runtime_preflight — read-only safety plan for an endpoint + categories (executable vs HELD, missing acknowledgements). - haiec_run_runtime_test — executes ONLY when the user explicitly confirms: userConfirmedRuntimeTest: true plus authorizationAcknowledged: true. Non-demo endpoints also need responseOnlyTargetAcknowledged: true. staticScanId binds the test to an AI System for later attach. - haiec_list_runtime_tests / haiec_get_runtime_test — discover and poll; attachableOnly + aiSystemId classify what can feed an Evaluation. To fold qualified runtime evidence into Assurance, attach the runtime test to a NEW run: haiec_run_assurance with attachRuntimeTestId (canonical engines.runtime executionMode "attach"). Policy/intent evidence: haiec_get/submit_capability_declaration and haiec_get/submit_operating_envelope (DRAFT only — approval stays dashboard-owned) after user confirmation; draft constraints must be presented to the user as a proposal, never invented from code. Outputs: haiec_issue_assurance_package (userConfirmed) issues the PRIVATE Decision Receipt; haiec_get_package reads state/integrity — by exact packageId, or by evaluationId for the canonical representative package (the same PUBLIC > PRIVATE > REVOKED selection the dashboard shows); haiec_publish_package (userConfirmedPublish — distinct flag) publishes publicly; haiec_revoke_package (userConfirmed + reason) revokes. Completed Evaluations are visible in the dashboard even with NO_RECEIPT. Never translate UNKNOWN / NOT_ASSESSED / EVIDENCE_NEEDED into PASS or FAIL. Evidence workflow: first inspect the local material with native IDE tools and choose an existing supported intakeProfile; never invent a profile or silently fall back after typed validation fails. Before upload, show one human-readable preview with: Provided by [user-confirmed display label or unspecified], server-verified organization/key attribution, Normalized using [actual IDE agent/LogSense name + version when available], destination organization/System/ binder, investigation ID/state, source references/time window, record/chunk counts, normalized facts, separate AI hypotheses, redactions, and limitations. Ask once whether to send that exact batch. Evidence upload (haiec_ingest_structured / haiec_ingest_logs) requires userConfirmedUpload: true reflecting real user approval. Use 512 KB / 5,000-record bounded chunks with stable clientBatchKey values. Return the receipt verbatim; it is EVIDENCE_INGESTED, not EVIDENCE_EVALUATED or GAP_CLOSED. Attach its producerRunId to a NEW Evaluation, then explain the before/after facts and remaining proof boundary. Telemetry, evidence, and runtime are optional — never blockers for static Assurance.

## Guided Assurance (how to act on open items) Your AI guides the assurance process. HAIEC determines the evidence and Assurance state. After an Evaluation: 1. Say what HAIEC ESTABLISHED first — established facts need no action. 2. Use haiec_get_agent_audit and its resolutionGroups field to group remaining open items by evidence need (e.g. "11 open questions reduce to 3 evidence needs"). Ask ONE useful question at a time, not one per row. 3. Use verificationNeeded verbatim for the resolution step. Do not re-run the same scan expecting progress when the gap needs a different evidence family (provider/IAM export, runtime witness, policy authorization, deployment continuity). 4. Offer to help obtain or evaluate evidence — uploads always require explicit user confirmation, then a NEW Evaluation before claiming a delta. 5. UNKNOWN means the question remains open — explain what is already known, why current evidence cannot answer the rest, and what would resolve it. UNKNOWN != PASS and UNKNOWN != FAIL.

## 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

3. Repository instructions — AGENTS.md

Devin discovers AGENTS.md at the repository root natively. Add the following section — it contains no credentials.

# AGENTS.md (repository root) — Devin reads this natively

## HAIEC Assurance (external service)

This repository is connected to a HAIEC AI System through the HAIEC
GitHub App. Trigger remote assurance through the HAIEC Assurance API —
never by modifying source code.

### Credentials and configuration

- Read HAIEC_BASE_URL, HAIEC_API_KEY, HAIEC_AI_SYSTEM_ID, and
  HAIEC_SOURCE_ASSET_ID from the environment or from the project's
  non-public .env.local if the developer has placed them there.
- NEVER print, display, commit, or write HAIEC_API_KEY to any file,
  response, log, or commit. If it is missing, ask the user to export it.
- NEVER send a GitHub token, GITHUB_TOKEN, X-GitHub-Token, or any
  repository credential to HAIEC. The GitHub App handles repository access.
- NEVER send an organizationId; the organization comes from the API key.

## When the user asks to run HAIEC Assurance

1. Confirm all four configuration values are present; if
   HAIEC_SOURCE_ASSET_ID is missing, list evaluation sources via
   GET {HAIEC_BASE_URL}/api/v1/systems/{systemId}/evaluation-sources and use only a
   VERIFIED source — never guess a repository URL.
2. POST {HAIEC_BASE_URL}/api/v1/assurance/runs with header
   "Authorization: Bearer $HAIEC_API_KEY" and a fresh Idempotency-Key:
   { "aiSystemId": "...",
     "engines": { "static": { "enabled": true,
       "executionMode": "api", "sourceAssetId": "..." } } }
3. Poll GET {HAIEC_BASE_URL}/api/v1/assurance/runs/{runId} every 15-30s. Stop on a
   terminal failure and report the structured failure object.
4. When evaluation.evaluationId appears, GET links.summary, then
   links.agentAudit, and report: run ID, evaluation ID, disposition, what
   HAIEC established, what it did not establish, evidence gaps,
   verification items, limitations, and links.report / links.passport /
   links.dashboard.
5. NEVER manufacture PASS. If evidence is unavailable or partial, say so.
6. Explaining findings is fine; remediation requires a separate user
   instruction.

## Reading a HAIEC result (canonical order)

1. POST Assurance Run → 2. poll the run → 3. GET links.summary →
4. GET links.agentAudit → 5. GET links.report ONLY when deeper technical
   detail is required (the agent-audit answers most questions).

The agent-audit is a deterministic projection of the exact persisted
evaluation. Use it verbatim:

- narrative.established — what HAIEC actually established
- narrative.unestablished — material facts it did NOT establish
- narrative.notAssessed — areas explicitly not assessed
- narrative.evidenceGaps — the exact missing evidence
- narrative.limitations — bounded limitations of the result
- authoritySummary — authority-plane state
- verificationItems[] — per item: whatHaiecFound, whatItEstablishes,
  whatHaiecDidNotEstablish, whyItMatters, verificationNeeded,
  affectedQuestionIds, affectedPathIds, evidenceRefs, boundary

verificationNeeded is the authoritative evidence request. Explain it in
plain language if helpful, but never invent evidence requirements beyond
it and never present the paraphrase as HAIEC truth.

Never translate:
- NOT_ASSESSED → FAIL
- UNKNOWN → FAIL
- MISSING_EVIDENCE → VULNERABILITY
- NO_RUNTIME_WITNESS → ACTION_DID_NOT_OCCUR
- EVIDENCE_INGESTED → GAP_CLOSED

## IDE evidence workflow (only when the user explicitly asks)

The IDE agent investigates and normalizes; HAIEC qualifies and evaluates. Do
not create a second investigator, normalization path, evidence store, or
verdict. Keep source facts separate from AI interpretation and never present a
hypothesis as an observed event or HAIEC finding.

1. DISCOVER — call haiec_preflight for the exact tenant and AI System. Read
   haiec_get_system_evidence, haiec_control_assurance, haiec_control_results,
   haiec_control_replay, and the relevant Agent Audit/evidence-gap output.
   For a forensic case, call haiec_list_investigations first; continue an
   existing persisted scenario when it matches. Use
   haiec_scenario_preflight + haiec_prepare_scenario only for a new case.
2. INVESTIGATE — use the IDE's authorized local tools to inspect permitted
   source, configuration, manifests, logs, commits, builds and local
   diagnostics. Preserve exact file/line/artifact references, commit/build
   identity, source timestamps, hashes, supporting and contradictory facts,
   and source limitations. Do not imply access to deployed IAM, cloud
   permissions, production transactions, or customer databases.
3. COLLECT + NORMALIZE — choose a supported existing contract from
   haiec_scenario_preflight and the advertised intake profiles. Prefer
   haiec_ingest_structured for JSON/JSONL/CSV, haiec_ingest_logs for logs,
   logsense_bundle only for a valid supported LogSense bundle,
   haiec_submit_local_scan only for an integrity-qualified local bundle, and
   haiec_submit_trace_facts only for declared workflow context. A typed
   intakeProfile is a caller-declared proposal: never guess from file shape
   silently and never fall back to generic after a typed-schema failure.
4. PREVIEW — before any write, show one review in plain language:
   Provided by: the username the user confirmed in the IDE (or
   unspecified); server-verified API-key and organization attribution are
   shown separately. Normalized using: the actual IDE agent/LogSense name and
   version when available. Also show the destination organization, AI System,
   binder, existing scenarioRunId, source files/artifacts and time window,
   record/chunk counts, selected intakeProfile, normalized facts, AI
   hypotheses (separate), redactions/omissions, and limitations. This is a
   preview, not a human approval receipt or an assurance result.
5. CONFIRM + SUBMIT — ask once whether to send that exact batch. Only after
   the user confirms call haiec_ingest_structured or haiec_ingest_logs with
   userConfirmedUpload: true. Reconfirm only if the outbound data materially
   changes. Do not issue approval receipts, authorize policy, execute runtime
   attacks, change cloud/deployed systems, or invoke Kill Switch actions.
   Keep each payload within 512 KB / 5,000 records. For larger files, split
   deterministically on record boundaries, preserve the same scenario binding,
   and use a stable clientBatchKey derived from file digest + chunk index.
6. RECEIPT — return the actual ingestionId / producerRunId, accepted,
   rejected, failures, qualification/input errors, exact system/case binding,
   and limitations verbatim. A receipt is EVIDENCE_INGESTED only; it is not
   EVIDENCE_EVALUATED, CONTROL_SATISFIED, or GAP_CLOSED.
7. RE-EVALUATE + EXPLAIN — attach the receipt producerRunId to a NEW
   Assurance run with externalEvidenceAttachments [{ "producerId":
   "structured-ingress", "producerRunId": "<receipt.producerRunId>" }].
   Poll, then compare the immutable prior and new evaluation facts. Explain
   HAIEC-established facts, AI interpretation, and the proof boundary/next
   evidence in separate sections. Historical evaluations never change.

Never upload .env files, credentials, secrets, private keys, tokens, session
cookies, repository archives, or unrelated files. If no eligible binder exists,
say the source must be connected in HAIEC first; never invent binderId. If the
key returns 403 on intake, it lacks evidence:ingest — ask the user to create a
key with that explicit scope.

- Capability manifest: /.well-known/haiec-capabilities.json

4. The underlying API calls

The instructions above perform exactly this — nothing Devin-specific:

curl -X POST "$HAIEC_BASE_URL/api/v1/assurance/runs" \
  -H "Authorization: Bearer $HAIEC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen || date +%s)" \
  -d "{
    \"aiSystemId\": \"$HAIEC_AI_SYSTEM_ID\",
    \"engines\": { \"static\": {
        \"enabled\": true,
        \"executionMode\": \"api\",
        \"sourceAssetId\": \"$HAIEC_SOURCE_ASSET_ID\"
    } }
  }"

A server-side TypeScript equivalent using native fetch:

// server-side only — never in browser/bundled code
const res = await fetch(`${process.env.HAIEC_BASE_URL}/api/v1/assurance/runs`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HAIEC_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    aiSystemId: process.env.HAIEC_AI_SYSTEM_ID,
    engines: { static: { enabled: true,
      executionMode: 'api',
      sourceAssetId: process.env.HAIEC_SOURCE_ASSET_ID } },
  }),
})
const run = await res.json() // { runId, links.self, ... } — poll until evaluation.evaluationId

What the agent should do

After setup, “Run HAIEC Assurance on this application” should make Devin:

  1. Discover the exact tenant, AI System, controls, evidence gaps, results, replay status, and any existing persisted investigation before acting.
  2. Investigate permitted local source, configuration, logs, commits, builds, and diagnostics with native IDE tools; preserve exact references and separate facts from hypotheses.
  3. Choose an existing supported evidence contract and caller-declared intakeProfile; never silently infer a profile or fall back after typed validation fails.
  4. Prepare one preview showing Provided by, Normalized using, destination, investigation binding, source/time scope, counts, normalized facts, separate AI hypotheses, redactions, and limitations.
  5. Ask the user to confirm that exact outbound batch once; only then call the canonical ingestion tool with userConfirmedUpload: true.
  6. Keep uploads within 512 KB / 5,000 records; split deterministically with stable clientBatchKey values and preserve scenario binding on every chunk.
  7. Return ingestionId / producerRunId, accepted/rejected/failure counts, qualification errors, bindings, and limitations verbatim.
  8. Attach producerRunId to a NEW Evaluation only when the user wants the evidence evaluated; compare immutable prior/new facts without mutating history.
  9. Explain HAIEC-established facts, AI interpretation, and the proof boundary/next responsible action separately; never claim EVIDENCE_INGESTED closed a gap.
  • Never display, commit, or log HAIEC_API_KEY.
  • Never send a GitHub token or organizationId to HAIEC.
  • Never present missing or partial evidence as PASS.
  • Never translate NOT_ASSESSED or UNKNOWN into FAIL, or missing evidence into a vulnerability.
  • Never upload .env files, credentials, secrets, private keys, or repository archives as evidence.
  • An ingestion receipt means EVIDENCE_INGESTED — never EVIDENCE_EVALUATED or GAP_CLOSED.
  • Never set userConfirmedRuntimeTest or authorizationAcknowledged on your own — they must reflect actual user statements.
  • Running a scan must not change application code; remediation is a separate instruction.