openapi: 3.0.3
info:
  title: Chick-fil-A BOVINE Accounts API
  description: BOVI(n)E — Building Operational Visibility Into (n) Environments — is a serverless, single-page application open-sourced by Chick-fil-A (github.com/chick-fil-a/bovine) that provides a "10,000 foot view" across all of an enterprise's AWS accounts in a multi-account strategy. The backend runs on AWS Lambda behind AWS API Gateway, with data stored in DynamoDB and audit reports in S3. The API surfaces account inventory, IAM users and roles, EC2 instances, public IPs, security groups, load balancers, RDS/DynamoDB/ Redshift databases, S3 buckets, and compliance audit reports for security and governance teams. This specification was generated from the project's serverless.yml route definitions and Python Lambda handlers.
  version: '1.0'
  x-generated-from: documentation
  x-source-url: https://github.com/chick-fil-a/bovine
  x-last-validated: '2026-06-02'
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  license:
    name: See repository
    url: https://github.com/chick-fil-a/bovine
servers:
- url: https://api.example.com
  description: Deployment-specific AWS API Gateway endpoint. BOVINE is self-hosted; the host is configured per-deployment via the serverless domainName setting.
tags:
- name: Accounts
  description: AWS account inventory and metadata operations.
paths:
  /api/accounts:
    get:
      operationId: getAccounts
      summary: Chick-fil-A List Accounts
      description: Lists all AWS accounts tracked in the BOVINE DynamoDB accounts table.
      tags:
      - Accounts
      responses:
        '200':
          description: Accounts returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountListItem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/account:
    get:
      operationId: getAccount
      summary: Chick-fil-A Get Account
      description: Returns detailed metadata and risk posture for a single AWS account, looked up by account number or alias.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/AccountParam'
      responses:
        '200':
          description: Account detail returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetail'
        '404':
          description: Account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/addAccount:
    post:
      operationId: addAccount
      summary: Chick-fil-A Add Account
      description: Adds an AWS account to the BOVINE accounts table. The account number must be a 12-digit numeric string.
      tags:
      - Accounts
      requestBody:
        required: true
        description: AWS account metadata to add.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAccountRequest'
      responses:
        '200':
          description: Account added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddAccountResponse'
        '500':
          description: Incorrect account number or account not added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddAccountResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    AccountParam:
      name: account
      in: query
      required: true
      description: The AWS account number (12-digit) or account alias to scope the request to.
      schema:
        type: string
      example: '123456789012'
  schemas:
    AddAccountResponse:
      type: object
      description: Response from adding an account.
      properties:
        response:
          type: string
          description: The result of the add operation, or an error message.
          example: added
    MessageResponse:
      type: object
      description: Generic message wrapper used for not-found and informational responses.
      properties:
        Message:
          type: string
          description: A human-readable message.
          example: Account not found.
    AccountDetail:
      type: object
      description: Detailed AWS account metadata and risk posture.
      properties:
        Account:
          type: object
          description: The account detail payload.
          properties:
            accountNum:
              type: string
              description: The 12-digit AWS account number.
              example: '123456789012'
            owner:
              type: string
              description: The account owner.
              example: Platform Team
            alias:
              type: string
              description: The account alias.
              example: prod-platform
            email:
              type: string
              format: email
              description: The account root contact email.
              example: aws-prod@example.com
            iam:
              type: integer
              description: Number of IAM users in the account.
              example: 18
            publicIP:
              type: integer
              description: Number of public IP addresses in the account.
              example: 6
            riskysg:
              type: integer
              description: Number of risky security groups detected.
              example: 2
            unusedsg:
              type: integer
              description: Number of unused security groups detected.
              example: 5
            bastion:
              type: string
              description: The bastion host identifier, if present.
              example: bastion-prod-1
            risk_score:
              type: integer
              description: The computed risk score for the account.
              example: -1
            admins:
              type: integer
              description: Number of admin group members.
              example: 3
    AddAccountRequest:
      type: object
      description: Request body to add an AWS account to BOVINE.
      required:
      - accountNum
      properties:
        accountNum:
          type: string
          description: The 12-digit AWS account number.
          example: '123456789012'
        alias:
          type: string
          description: The account alias.
          example: prod-platform
        email:
          type: string
          format: email
          description: The account root contact email.
          example: aws-prod@example.com
        AccountOwner:
          type: string
          description: The account owner.
          example: Platform Team
        remediate:
          type: boolean
          description: Whether automated remediation is enabled.
          example: false
    AccountListItem:
      type: object
      description: A summary AWS account record from the accounts table.
      properties:
        accountNum:
          type: string
          description: The 12-digit AWS account number.
          example: '123456789012'
        alias:
          type: string
          description: The account alias.
          example: prod-platform
        email:
          type: string
          format: email
          description: The account root contact email.
          example: aws-prod@example.com
        AccountOwner:
          type: string
          description: The account owner.
          example: Platform Team
        remediate:
          type: boolean
          description: Whether automated remediation is enabled for the account.
          example: false