Field Types Specification

# Schema definition
ConceptID:
  type: string
  pattern: "^C-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"

# Schema definition
InteractionID:
  type: string
  pattern: "^I-[A-Z0-9]{2,8}-[A-Z]{1,16}-[A-Z]{1,16}-[0-9]{3}$"

# Schema definition
FlowID:
  type: string
  pattern: "^F-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"

# Schema definition
ScenarioID:
  type: string
  pattern: "^S-[A-Z0-9]{2,8}-[A-Z0-9-]{1,24}-[0-9]{3}$"

# Schema definition
ExplorationID:
  type: string
  pattern: "^E-[A-Z0-9]{2,8}-[A-Z0-9-]{1,24}-[0-9]{3}-[0-9]{2}$"

# Schema definition
TraceID:
  type: string
  pattern: "^T-[A-Z0-9]{2,8}-[A-Z0-9-]{1,24}-[0-9]{3}-[0-9]{2}-[0-9]{2}$"

# Schema definition
FindingID:
  type: string
  pattern: "^FD-[A-Z0-9]{2,8}-[A-Z]{1,16}-[0-9]{3}$"

# Schema definition
PredicateID:
  type: string
  pattern: "^P-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"

# Schema definition
InvariantID:
  type: string
  pattern: "^INV-[A-Z0-9]{2,8}-[A-Z0-9-]{1,32}$"

# Schema definition
EntryPointID:
  type: string
  pattern: "^EP-[A-Z0-9-]{1,128}$"

# Schema definition
ProjectionID:
  type: string
  pattern: "^PRJ-[A-Z0-9-]{1,128}$"

# Schema definition
GeneratorID:
  type: string
  pattern: "^GEN-[A-Z0-9-]{1,24}-[0-9]{3}$"

# Schema definition
PatchID:
  type: string
  pattern: "^PATCH-[A-Z0-9]{2,8}-[0-9]{3}$"

# Schema definition
ArtifactID:
  oneOf:
    - $ref: "#/$defs/ConceptID"
    - $ref: "#/$defs/InteractionID"
    - $ref: "#/$defs/FlowID"
    - $ref: "#/$defs/ScenarioID"
    - $ref: "#/$defs/ExplorationID"
    - $ref: "#/$defs/TraceID"
    - $ref: "#/$defs/FindingID"
    - $ref: "#/$defs/PredicateID"
    - $ref: "#/$defs/InvariantID"
    - $ref: "#/$defs/GeneratorID"
    - $ref: "#/$defs/PatchID"

# Schema definition
Criticality:
  type: string
  enum: [P0, P1, P2, P3]

# Schema definition
Verdict:
  type: string
  enum: [PASS, FAIL, INCONCLUSIVE, BLOCKED, SKIPPED]

# Schema definition
InvariantState:
  type: string
  enum: [HOLDS, VIOLATED, UNKNOWN, NOT_APPLICABLE]

# Schema definition
ArtifactStatus:
  type: string
  enum: [DRAFT, REVIEW, PLANNED, ACTIVE, DEPRECATED, ARCHIVED]

Extensions:
  type: object
  additionalProperties: true
 
# Example usage in an artifact
extensions:
  example_ext:
    some_field: "value"

# Schema definition
Severity:
  type: string
  enum: [CRITICAL, HIGH, MEDIUM, LOW, INFO]

# Schema definition
FindingCategory:
  type: string
  enum: [AUTHZ, AUTHN, CRYPTO, CONFIG, INJECT, LEAK, LOGIC, RACE, SSRF, IDOR]

# Schema definition
ConceptType:
  type: string
  enum: [IDENTITY, RESOURCE, POLICY, CREDENTIAL, TOKEN, KEY, CONFIGURATION]

# Schema definition
ActionType:
  type: string
  enum: [CREATE, READ, UPDATE, DELETE, ACCESS, EXECUTE, ASSUME, GRANT, REVOKE]

# Schema definition
InvariantRef:
  type: object
  required: [id]
  properties:
    id:
      $ref: "#/$defs/InvariantID"
    state:
      $ref: "#/$defs/InvariantState"
    notes:
      type: string

invariant:
  id: INV-AWS-NO-PUBLIC-S3
  state: VIOLATED
  notes: "Public bucket found in staging environment"

# Schema definition
EntryPoint:
  type: object
  required: [interaction]
  properties:
    interaction:
      $ref: "#/$defs/InteractionID"
    parameters:
      type: array
      items:
        $ref: "#/$defs/Parameter"
    preconditions:
      type: array
      items:
        type: string

entry_point:
  interaction: I-AWS-ASSUME-ROLE-001
  parameters:
    - name: role_arn
      type: string
      required: true
    - name: session_name
      type: string
      required: false
  preconditions:
    - "Caller has sts:AssumeRole permission"
    - "Target role trust policy allows assumption"
 
### TangibleLocation
 
Records **where a surface is concretely accessible/observable** for testers and auditors (e.g., a full web URL).
 
This field type is intentionally declarative and MUST NOT encode security logic. Use invariants (`INV-*`) for logic.
 
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `kind` | string | Yes | Locator kind (`web_url`, `api_url`, `graphql`, `cli`, `email`, `file`, `event`) |
| `web_url_template` | string | No | Templated fully-qualified URL (use placeholders like `{host}`) |
| `example_urls` | string[] | No | Concrete URLs a tester can paste into a browser/curl |
| `notes` | string | No | Scoping notes (auth preconditions, flags, instance settings) |
 
```yaml
# Schema definition
TangibleLocation:
  type: object
  required: [kind]
  properties:
    kind:
      type: string
      enum: [web_url, api_url, graphql, cli, email, file, event]
    web_url_template:
      type: string
    example_urls:
      type: array
      items:
        type: string
    notes:
      type: string

tangible_locations:
  - kind: web_url
    web_url_template: "https://{host}/{namespace}/{project}/-/tags.rss"
    example_urls:
      - "https://gitlab.example.com/gitlab-org/gitlab/-/tags.rss"
    notes: "RSS feed for tags; unauthenticated for public projects"

parameters:
  - name: role_arn
    type: string
    required: true
    description: "ARN of the role to assume"
    constraints:
      - type: pattern
        value: "^arn:aws:iam::[0-9]{12}:role/.+$"
  - name: duration_seconds
    type: integer
    required: false
    default: 3600
    constraints:
      - type: range
        min: 900
        max: 43200

# Schema definition
Constraint:
  type: object
  required: [type]
  properties:
    type:
      type: string
      enum: [pattern, range, enum, length, custom]
    value:
      # Any type - depends on constraint type
    min:
      type: number
    max:
      type: number
    message:
      type: string

# Schema definition
FlowStep:
  type: object
  required: [order, interaction]
  properties:
    order:
      type: integer
      minimum: 1
    interaction:
      $ref: "#/$defs/InteractionID"
    description:
      type: string
    conditional:
      type: string
    on_success:
      type: integer
    on_failure:
      type: integer

steps:
  - order: 1
    interaction: I-AWS-GET-CALLER-IDENTITY-001
    description: "Verify current identity"
  - order: 2
    interaction: I-AWS-ASSUME-ROLE-001
    description: "Assume target role"
    on_success: 3
    on_failure: 4
  - order: 3
    interaction: I-AWS-GET-CREDENTIALS-001
    description: "Retrieve session credentials"
  - order: 4
    interaction: I-AWS-LOG-FAILURE-001
    description: "Log assumption failure"

# Schema definition
Finding:
  type: object
  required: [id, title, severity, category, exploration, description, impact, remediation]
  properties:
    id:
      $ref: "#/$defs/FindingID"
    title:
      type: string
      maxLength: 100
    severity:
      $ref: "#/$defs/Severity"
    category:
      $ref: "#/$defs/FindingCategory"
    exploration:
      $ref: "#/$defs/ExplorationID"
    invariant:
      $ref: "#/$defs/InvariantID"
    description:
      type: string
    impact:
      type: string
    remediation:
      type: string
    evidence:
      type: array
      items:
        $ref: "#/$defs/Evidence"

# Schema definition
Evidence:
  type: object
  required: [type, description]
  properties:
    type:
      type: string
      enum: [log, screenshot, request, response, code, configuration]
    description:
      type: string
    data:
      type: string
    url:
      type: string
      format: uri

# Schema definition
ConceptList:
  type: array
  items:
    $ref: "#/$defs/ConceptID"
  uniqueItems: true

concepts:
  - C-AWS-IAM-ROLE
  - C-AWS-TRUST-POLICY
  - C-AWS-SESSION-TOKEN

# Schema definition
InteractionList:
  type: array
  items:
    $ref: "#/$defs/InteractionID"
  uniqueItems: true

interactions:
  - I-AWS-ASSUME-ROLE-001
  - I-AWS-GET-CREDENTIALS-002
  - I-AWS-VALIDATE-TOKEN-003

# Schema definition
InvariantList:
  type: array
  items:
    oneOf:
      - $ref: "#/$defs/InvariantID"
      - $ref: "#/$defs/InvariantRef"
  uniqueItems: true

invariants:
  - INV-AWS-NO-PUBLIC-S3
  - INV-AWS-ADMIN-MFA

invariants:
  - id: INV-AWS-NO-PUBLIC-S3
    state: HOLDS
  - id: INV-AWS-ADMIN-MFA
    state: VIOLATED
    notes: "Service account lacks MFA"

# Schema definition
FindingList:
  type: array
  items:
    $ref: "#/$defs/FindingID"
  uniqueItems: true

findings:
  - FD-AWS-AUTHZ-001
  - FD-AWS-CONFIG-002

# Schema definition
FlowStepList:
  type: array
  items:
    $ref: "#/$defs/FlowStep"
  minItems: 1