Skip to content

API.md

Latest commit

 

History

History
284 lines (222 loc) · 7.45 KB

API.md

File metadata and controls

284 lines (222 loc) · 7.45 KB

Audits1984 JSON API

This document describes the JSON API for programmatic access to Audits1984.

Authentication

All API requests require authentication via a Bearer token in the Authorization header.

Generating a Token

Tokens are generated through the web interface. An authenticated auditor visits /auditor_token and clicks "Generate Token". The plaintext token is displayed once and cannot be retrieved again.

Tokens expire after 1 week. Only one active token exists per auditor; generating a new token invalidates any previous token.

Using a Token

Include the token in the Authorization header:

Authorization: Bearer <token>

All requests must also include:

Accept: application/json

Authentication Errors

Status Meaning
403 Forbidden Missing, invalid, or expired token

Sessions

List Sessions

GET /sessions

Returns a list of console sessions, ordered by creation time (newest first).

Query Parameters

Parameter Type Description
sensitive_only boolean When true, return only sessions that accessed sensitive data
pending_only boolean When true, return only sessions with no audits yet
from_date date (YYYY-MM-DD) Return sessions created on or after this date
to_date date (YYYY-MM-DD) Return sessions created on or before this date

Response

{
  "sessions": [
    {
      "id": 123,
      "user": "alice",
      "reason": "Investigating support ticket #456",
      "created_at": "2024-01-15T10:30:00Z",
      "sensitive": true,
      "audit_statuses": ["approved"]
    },
    {
      "id": 124,
      "user": "bob",
      "reason": "Checking permissions",
      "created_at": "2024-01-14T10:30:00Z",
      "sensitive": false,
      "audit_statuses": []
    }
  ]
}

Session Fields

Field Type Description
id integer Unique session identifier
user string or null Username of the person who ran the console session
reason string The reason provided when starting the console session
created_at string (ISO 8601) When the session was created
sensitive boolean Whether the session accessed any sensitive data
audit_statuses array of strings Status of each audit on this session (empty if unaudited)

Show Session

GET /sessions/:id

Returns detailed information about a single session, including all commands executed and any audits.

Response

{
  "session": {
    "id": 123,
    "user": "alice",
    "reason": "Investigating support ticket #456",
    "created_at": "2024-01-15T10:30:00Z",
    "sensitive": true,
    "command_batches": [
      {
        "sensitive": false,
        "justification": null,
        "commands": [
          "User.find(123)",
          "user.name"
        ]
      },
      {
        "sensitive": true,
        "justification": "Need to check payment details",
        "commands": [
          "user.credit_card_number"
        ]
      }
    ],
    "audits": [
      {
        "id": 456,
        "status": "approved",
        "notes": "Legitimate access for support case",
        "auditor_id": 1,
        "created_at": "2024-01-16T09:00:00Z",
        "updated_at": "2024-01-16T09:00:00Z"
      }
    ]
  }
}

Session Fields (Show)

Field Type Description
id integer Unique session identifier
user string or null Username of the person who ran the console session
reason string The reason provided when starting the console session
created_at string (ISO 8601) When the session was created
sensitive boolean Whether the session accessed any sensitive data
command_batches array Commands grouped by sensitive access context
audits array All audits for this session

Command Batch Fields

Commands are grouped into batches based on sensitive access. Each batch represents a sequence of commands that were either all non-sensitive, or all executed under the same sensitive access justification.

Field Type Description
sensitive boolean Whether these commands accessed sensitive data
justification string or null The justification provided for sensitive access (null for non-sensitive batches)
commands array of strings The console commands executed in this batch

Errors

Status Response Meaning
404 Not Found {"error": "Not found"} Session does not exist

Audits

Create Audit

POST /sessions/:session_id/audits

Creates a new audit for a session. The audit is associated with the authenticated auditor.

Request Body

{
  "audit": {
    "status": "approved",
    "notes": "Access was appropriate for the stated reason"
  }
}

Audit Parameters

Parameter Type Required Description
status string Yes One of: pending, approved, flagged
notes string No Auditor's notes explaining the audit decision

Status Values

Status Meaning
pending Audit has been started but not yet completed
approved Session access was appropriate and legitimate
flagged Session access was suspicious or inappropriate

Response

Status: 201 Created

{
  "audit": {
    "id": 456,
    "status": "approved",
    "notes": "Access was appropriate for the stated reason",
    "auditor_id": 1,
    "session_id": 123,
    "created_at": "2024-01-16T09:00:00Z",
    "updated_at": "2024-01-16T09:00:00Z"
  }
}

Errors

Status Response Meaning
404 Not Found {"error": "Not found"} Session does not exist
422 Unprocessable Entity {"error": "Validation failed", "messages": [...]} Invalid audit parameters
422 Unprocessable Entity {"error": "'invalid' is not a valid status"} Invalid status value

Update Audit

PATCH /sessions/:session_id/audits/:id
PUT /sessions/:session_id/audits/:id

Updates an existing audit. Only the auditor who created the audit can update it.

Request Body

{
  "audit": {
    "status": "flagged",
    "notes": "Upon further review, this access seems suspicious"
  }
}

Response

Status: 200 OK

{
  "audit": {
    "id": 456,
    "status": "flagged",
    "notes": "Upon further review, this access seems suspicious",
    "auditor_id": 1,
    "session_id": 123,
    "created_at": "2024-01-16T09:00:00Z",
    "updated_at": "2024-01-16T10:00:00Z"
  }
}

Errors

Status Response Meaning
404 Not Found {"error": "Not found"} Session or audit does not exist
422 Unprocessable Entity {"error": "Validation failed", "messages": [...]} Invalid audit parameters

Audit Response Fields

Field Type Description
id integer Unique audit identifier
status string The audit status: pending, approved, or flagged
notes string or null Auditor's notes explaining the decision
auditor_id integer ID of the auditor who created/updated the audit
session_id integer ID of the session being audited (only in create/update responses)
created_at string (ISO 8601) When the audit was created
updated_at string (ISO 8601) When the audit was last updated