Get Justification

Retrieve a detailed, human-readable justification for a scored event. Includes violation explanations mapped to compliance frameworks, remediation steps, and impacted frameworks.

GET https://api-production-56df.up.railway.app/justification

cURL

curl -X GET "https://api-production-56df.up.railway.app/justification?event_id=evt_a1b2c3d4-5678-9012-abcd-ef3456789012" \
  -H "X-API-Key: your-api-key"

200

{
  "event_id": "evt_a1b2c3d4-5678-9012-abcd-ef3456789012",
  "score": 62,
  "risk_level": "medium",
  "summary": "An AI coding assistant created a pull request to a high-sensitivity payments repository while accessing a secret-classified field. The action sequence is consistent with legitimate development, but the secret access requires review.",
  "score_justification": "The score of 62 (medium risk) was determined by the graph-based rule engine with 0.91 confidence. The primary contributors were: sensitivity_level_check (+25 points) triggered by the target repository's sensitivity level of 3, secret_field_access (+20 points) due to the agent reading an 'api_key' field classified as 'secret', pr_to_main_branch (+10 points) for creating a PR targeting the main branch, and session_action_coherence (+7 points) for a minor deviation in the expected action flow. No LLM fallback was needed as graph confidence exceeded the 0.8 threshold.",
  "violation_details": [
    {
      "violation": "secret_field_access_in_pr",
      "article": "Article 14",
      "framework": "EU AI Act",
      "explanation": "Article 14 requires human oversight measures for high-risk AI systems. The agent accessed a secret-classified field (api_key) during a code modification workflow without explicit human approval for secret access, which may compromise the human oversight requirement.",
      "consequence": "If the secret value is included in the PR diff or committed code, it could lead to credential exposure and a reportable security incident under the EU AI Act's transparency obligations."
    },
    {
      "violation": "secret_field_access_in_pr",
      "article": "CC6.1",
      "framework": "SOC2",
      "explanation": "CC6.1 requires logical and physical access controls for information assets. The AI agent's access to a secret-classified field during an automated workflow may bypass established access control procedures if the secret is not properly scoped.",
      "consequence": "Uncontrolled secret access could result in a SOC2 control deficiency finding during audit, particularly if the secret is exposed in version control history."
    },
    {
      "violation": "secret_field_access_in_pr",
      "article": "A.9.4.1",
      "framework": "ISO 27001",
      "explanation": "A.9.4.1 requires information access restriction based on access control policy. The agent accessed a secret field that may exceed the minimum access necessary for the stated task (fixing payment retry logic).",
      "consequence": "Violation of the principle of least privilege may result in non-conformity finding during ISO 27001 certification audit."
    }
  ],
  "remediation_steps": [
    "Review the PR diff to confirm the api_key value is not exposed in any committed file",
    "Enable GitHub secret scanning on the acme-corp/payments-service repository",
    "Configure the agent's policy to require explicit user confirmation before accessing secret-classified fields",
    "Add a pre-merge hook that blocks PRs containing detected secrets",
    "Consider reducing the agent's access scope to exclude secret-classified fields for routine code fix workflows"
  ],
  "frameworks_impacted": [
    "EU_AI_Act",
    "SOC2",
    "ISO_27001"
  ]
}

Requires X-API-Key header for authentication.

Query Parameters

event_id · string · required

UUID of the event to retrieve the justification for.

Response

event_id · string

The event identifier.

score · integer

The risk score assigned to the event (0-100).

risk_level · string

Risk level: none, low, medium, high, or critical.

summary · string

High-level summary of the risk assessment in plain language.

score_justification · string

Detailed explanation of how and why the score was calculated, including which rules fired and their contributions.

violation_details · array

Detailed breakdown of each violation detected, with compliance mapping.

Show violation detail properties

violation · string

The violation identifier (e.g., secret_field_access_in_pr).

article · string

The specific compliance article reference (e.g., Article 14).

framework · string

The compliance framework (e.g., EU AI Act, SOC2, ISO 27001).

explanation · string

Human-readable explanation of why this action violates the cited article.

consequence · string

Potential consequence of the violation if left unaddressed.

remediation_steps · array

Ordered list of recommended actions to remediate the identified risks.

frameworks_impacted · array

List of compliance framework identifiers that are affected by this event (e.g., EU_AI_Act, SOC2, ISO_27001, NIST_AI_RMF).

cURL

curl -X GET "https://api-production-56df.up.railway.app/justification?event_id=evt_a1b2c3d4-5678-9012-abcd-ef3456789012" \
  -H "X-API-Key: your-api-key"

200

{
  "event_id": "evt_a1b2c3d4-5678-9012-abcd-ef3456789012",
  "score": 62,
  "risk_level": "medium",
  "summary": "An AI coding assistant created a pull request to a high-sensitivity payments repository while accessing a secret-classified field. The action sequence is consistent with legitimate development, but the secret access requires review.",
  "score_justification": "The score of 62 (medium risk) was determined by the graph-based rule engine with 0.91 confidence. The primary contributors were: sensitivity_level_check (+25 points) triggered by the target repository's sensitivity level of 3, secret_field_access (+20 points) due to the agent reading an 'api_key' field classified as 'secret', pr_to_main_branch (+10 points) for creating a PR targeting the main branch, and session_action_coherence (+7 points) for a minor deviation in the expected action flow. No LLM fallback was needed as graph confidence exceeded the 0.8 threshold.",
  "violation_details": [
    {
      "violation": "secret_field_access_in_pr",
      "article": "Article 14",
      "framework": "EU AI Act",
      "explanation": "Article 14 requires human oversight measures for high-risk AI systems. The agent accessed a secret-classified field (api_key) during a code modification workflow without explicit human approval for secret access, which may compromise the human oversight requirement.",
      "consequence": "If the secret value is included in the PR diff or committed code, it could lead to credential exposure and a reportable security incident under the EU AI Act's transparency obligations."
    },
    {
      "violation": "secret_field_access_in_pr",
      "article": "CC6.1",
      "framework": "SOC2",
      "explanation": "CC6.1 requires logical and physical access controls for information assets. The AI agent's access to a secret-classified field during an automated workflow may bypass established access control procedures if the secret is not properly scoped.",
      "consequence": "Uncontrolled secret access could result in a SOC2 control deficiency finding during audit, particularly if the secret is exposed in version control history."
    },
    {
      "violation": "secret_field_access_in_pr",
      "article": "A.9.4.1",
      "framework": "ISO 27001",
      "explanation": "A.9.4.1 requires information access restriction based on access control policy. The agent accessed a secret field that may exceed the minimum access necessary for the stated task (fixing payment retry logic).",
      "consequence": "Violation of the principle of least privilege may result in non-conformity finding during ISO 27001 certification audit."
    }
  ],
  "remediation_steps": [
    "Review the PR diff to confirm the api_key value is not exposed in any committed file",
    "Enable GitHub secret scanning on the acme-corp/payments-service repository",
    "Configure the agent's policy to require explicit user confirmation before accessing secret-classified fields",
    "Add a pre-merge hook that blocks PRs containing detected secrets",
    "Consider reducing the agent's access scope to exclude secret-classified fields for routine code fix workflows"
  ],
  "frameworks_impacted": [
    "EU_AI_Act",
    "SOC2",
    "ISO_27001"
  ]
}