Grepr Masking API

openapi: 3.2.0
info:
  title: Grepr Masking API
  version: 1.0.0
  description: 'Operations tagged Masking across 2 of this provider''s published API definitions: grepr-openapi.json, grepr.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Masking
paths:
  /v1/masking/mask:
    post:
      description: Applies a masking operator's masks to sample log events and returns the masked result for each, so the editor can preview a configuration without deploying it. The operator's predicate gates which logs are masked in production, not how, so it is ignored here and the masks are applied to every sample.
      operationId: mask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaskingRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaskingResponse'
          description: Sample masked successfully.
        '400':
          description: The masking configuration is invalid or could not be compiled.
        '401':
          description: Unauthorized
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Apply masks to samples
      tags:
      - Masking
components:
  schemas:
    MaskingResult:
      description: The masked results, aligned by position with the request's samples.
      properties:
        maskedAttributes:
          additionalProperties:
            $ref: '#/components/schemas/Any'
          description: The sample attributes after masking, unchanged when no mask matched.
          type: object
        maskedCount:
          description: The number of substrings replaced across the message and attributes; zero when nothing matched.
          example: 3
          format: int32
          type: integer
        maskedMessage:
          description: The sample message after masking, unchanged when no mask matched.
          example: user [email] signed in from [ip]
          type: string
      required:
      - maskedAttributes
      type: object
    DatadogQueryPredicate:
      properties:
        query:
          default: ''
          description: The datadog query used by the predicate. See https://docs.datadoghq.com/tracing/trace_explorer/query_syntax
          example: service:grepr-service-1
          type: string
        type:
          description: A predicate that checks if an event matches a datadog query.
          enum:
          - datadog-query
          type: string
      required:
      - query
      - type
      type: object
    NrqlQueryPredicate:
      properties:
        query:
          default: ''
          description: The Nrql query used by the predicate. See https://docs.newrelic.com/docs/nrql
          example: SELECT * FROM Log WHERE service = 'grepr-service-1'
          type: string
        strict:
          default: true
          description: Whether the query should be parsed in strict mode.
          type: boolean
        type:
          description: A predicate that checks if an event matches an NRQL query.
          enum:
          - nrql-query
          type: string
      required:
      - query
      - type
      type: object
    NewRelicQueryPredicate:
      properties:
        query:
          default: ''
          description: 'The New Relic query used by the predicate. See https://docs.newrelic.com/docs/logs/ui-data/query-syntax-logs/ '
          example: service:grepr-service-1
          type: string
        type:
          description: A predicate that checks if an event matches a New Relic query.
          enum:
          - newrelic-query
          type: string
      required:
      - query
      - type
      type: object
    MaskingRequest:
      properties:
        masking:
          $ref: '#/components/schemas/MaskingOperator'
        samples:
          default: []
          description: The sample log events to apply the masks to.
          items:
            $ref: '#/components/schemas/MaskingSample'
          maxItems: 20
          minItems: 0
          type: array
      required:
      - masking
      - samples
      type: object
    MaskingResponse:
      properties:
        results:
          description: The masked results, aligned by position with the request's samples.
          items:
            $ref: '#/components/schemas/MaskingResult'
          type: array
      required:
      - results
      type: object
    Mask:
      description: 'A mask: the regular expression to match, and how to rewrite the match. May also be written as a bare regex string when no replacement or preserved prefix is needed.'
      example:
        email: \S+@\S+
      properties:
        preserveThrough:
          description: Delimiter ending a prefix of the match that is kept verbatim instead of being replaced. The match is split at the first occurrence of this text, so a regex matching "?token=abc123" with a delimiter of "=" keeps "?token=" and rewrites only the value. When the delimiter does not occur in the match, the whole match is replaced.
          example: '='
          maxLength: 16
          minLength: 1
          type: string
        regex:
          description: 'Regular expression whose matches are rewritten. Must be compatible with Hyperscan syntax: no lookbehind and no backreferences. Prefer unbounded repeats (`+`, `*`) over bounded ones (`{1,50}`) — a bounded repeat is expanded into that many copies of the pattern and can exceed the compiler''s size limit.'
          example: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}'
          type: string
        replacement:
          description: Text substituted for the match. Defaults to the mask's label in square brackets, e.g. a mask labeled "email" becomes "[email]".
          example: <redacted>
          maxLength: 64
          minLength: 0
          type: string
      required:
      - regex
      type: object
    MetricEventPredicate:
      properties:
        filterTags:
          additionalProperties:
            default: {}
            description: The set of tags to query for. If unspecified, all tags are queried.
            example:
              env:
              - prod
              service:
              - my-app
            items:
              default: '{}'
              description: The set of tags to query for. If unspecified, all tags are queried.
              example: '{"service":["my-app"],"env":["prod"]}'
              type: string
            type: array
            uniqueItems: true
          default: {}
          description: The set of tags to query for. If unspecified, all tags are queried.
          example:
            env:
            - prod
            service:
            - my-app
          type: object
        metricNames:
          default: []
          description: The names of the metrics to query. Must not be empty.
          example:
          - cpu.load
          - cpu.utilization
          items:
            description: The names of the metrics to query. Must not be empty.
            example: '["cpu.load","cpu.utilization"]'
            type: string
          maxItems: 2147483647
          minItems: 1
          type: array
        query:
          type: string
        type:
          description: A predicate that checks if an event matches a metrics query.
          enum:
          - metric-predicate
          type: string
      required:
      - metricNames
      - query
      - type
      type: object
    AttributeMask:
      description: Masks to apply to attribute values. Each entry names an attribute path (as a list of segments) and the masks to apply to the value at that path. Only string values at the exact path are masked; missing or non-string attributes are skipped. Paths must be unique. The same matching rules as messageMasks apply.
      example:
      - masks:
          email: \S+@\S+
        path:
        - user
        - contact
      properties:
        masks:
          additionalProperties:
            $ref: '#/components/schemas/Mask'
          description: Masks to apply to the value at this path, as a map of label to mask. The same matching rules as messageMasks apply.
          example:
            email: \S+@\S+
          type: object
        path:
          description: Attribute path to mask, as a list of segments.
          example:
          - user
          - contact
          items:
            description: Attribute path to mask, as a list of segments.
            example: '["user","contact"]'
            type: string
          maxItems: 2147483647
          minItems: 1
          type: array
      required:
      - masks
      - path
      type: object
    EventPredicate:
      description: Predicate applied to rows before analytical aggregation.
      discriminator:
        mapping:
          and-predicate: '#/components/schemas/AndEventPredicate'
          datadog-query: '#/components/schemas/DatadogQueryPredicate'
          metric-predicate: '#/components/schemas/MetricEventPredicate'
          newrelic-query: '#/components/schemas/NewRelicQueryPredicate'
          nrql-query: '#/components/schemas/NrqlQueryPredicate'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/AndEventPredicate'
      - $ref: '#/components/schemas/DatadogQueryPredicate'
      - $ref: '#/components/schemas/MetricEventPredicate'
      - $ref: '#/components/schemas/NewRelicQueryPredicate'
      - $ref: '#/components/schemas/NrqlQueryPredicate'
      properties:
        query:
          type: string
        type:
          type: string
      required:
      - type
      type: object
    MaskingOperator:
      properties:
        attributeMasks:
          default: []
          description: Masks to apply to attribute values. Each entry names an attribute path (as a list of segments) and the masks to apply to the value at that path. Only string values at the exact path are masked; missing or non-string attributes are skipped. Paths must be unique. The same matching rules as messageMasks apply.
          example:
          - masks:
              email: \S+@\S+
            path:
            - user
            - contact
          items:
            $ref: '#/components/schemas/AttributeMask'
          type: array
        messageMasks:
          additionalProperties:
            $ref: '#/components/schemas/Mask'
          default: {}
          description: Masks to apply to the log message, as a map of label to mask. A mask may be written as a bare regex string, in which case each match is replaced with the label in square brackets — a match of the regex labeled "email" becomes "[email]". Labels may be up to 64 characters. Overlapping matches resolve to the leftmost match first, then the longest; declaration order breaks remaining ties, so declare more specific patterns first.
          example:
            email: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
          type: object
        name:
          example: operation_name
          pattern: '[a-z0-9_]{1,128}'
          type: string
        predicate:
          $ref: '#/components/schemas/EventPredicate'
        type:
          description: Masks sensitive substrings in log events by replacing regex matches with decorated labels.
          enum:
          - masking-operator
          type: string
      required:
      - attributeMasks
      - messageMasks
      - name
      - type
      type: object
      x-tags:
      - Transforms
    Any:
      description: A value that can be a primitive (String or number), a list, or a map.
      example:
      - 12
      - a
      - b: 1
      - - 1
        - 2
        - 3
    AndEventPredicate:
      properties:
        queries:
          default: []
          description: List of predicates that must all match for this predicate to match.
          items:
            $ref: '#/components/schemas/EventPredicate'
          maxItems: 2147483647
          minItems: 1
          title: Child predicates
          type: array
        type:
          description: A predicate that matches when every child predicate matches.
          enum:
          - and-predicate
          type: string
      required:
      - queries
      - type
      type: object
    MaskingSample:
      description: The sample log events to apply the masks to.
      properties:
        attributes:
          additionalProperties:
            description: Sample attributes the attribute masks are applied to.
            example:
              user:
                email: alice@example.com
            type: object
          default: {}
          description: Sample attributes the attribute masks are applied to.
          example:
            user:
              email: alice@example.com
          type: object
        message:
          description: Sample log message the masks are applied to. May be omitted to test attribute masks alone.
          example: user alice@example.com signed in from 10.1.2.3
          maxLength: 100000
          minLength: 0
          type: string
      required:
      - attributes
      type: object
  securitySchemes:
    grepr-api-key:
      in: header
      name: GREPR-API-KEY
      type: apiKey
    grepr-oidc:
      bearerFormat: JWT
      openIdConnectUrl: https://grepr-prod.us.auth0.com/.well-known/openid-configuration
      type: openIdConnect
x-refined-from:
- grepr-openapi.json
- grepr.json
x-tagGroups:
- name: Integrations
  tags:
  - Grepr-hosted Data Warehouse Integration
  - External S3 Data Warehouse Integration
  - Datadog Integration
  - New Relic Integration
  - Splunk Integration
  - Sumo Logic Integration
  - OpenTelemetry Integration
- name: Pipelines
  tags:
  - Jobs
  - Templates
  - Datasets
  - Status Metrics
  - External Triggers
  - Job Actions
  - Triggers
- name: Pipeline Components
  tags:
  - Operations
  - Transforms
  - Sources
  - Sinks
- name: Administration
  tags:
  - Users
  - Teams
  - Roles
  - Permission
  - Invitations
  - Activity Logs
- name: Organization
  tags:
  - Organizations
  - Access Configuration
  - Grepr API Key
  - Service Accounts
  - Signup
- name: Query & Analysis
  tags:
  - Job Anomalies
  - Grok Parsing
  - Query Parsing
  - Validation
- name: System
  tags:
  - Manifest