Skip to content

Rulesets API

Rulesets are collections of rules that can be applied together through policies. This API allows you to manage rulesets in Aegis.

Endpoints

List Rulesets

Retrieve a list of rulesets that match the specified name pattern.

GET /api/rulesets/{ruleset_name}

Path Parameters:

Parameter Description
ruleset_name Name or pattern to filter rulesets (e.g., exact name or wildcard pattern) 
curl -X GET "https://<your-instance>.aegis.pegasys.cloud/api/rulesets/demo" \
  -H "Authorization: Bearer <your_token>"

[
  {
    "name": "demo",
    "uuid": "6bc1814c-5705-5b6e-af99-104b91962282",
    "description": "Kubernetes deployment security rules",
    "labels": {
      "platform": "kubernetes",
      "resource": "deployment"
    },
    "rules": [
      {
        "name": "enforce-app-label",
        "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p",
        "enforce": true,
        "dryrun": false
      }
    ],
    "version": "1.0.0",
    "createdAt": "2025-06-01T10:00:00Z",
    "updatedAt": "2025-06-01T10:00:00Z"
  }
]

Get Ruleset by UUID

Retrieve a specific ruleset by its UUID.

GET /api/rulesets/uuid/{uuid}

Path Parameters:

Parameter Description
uuid The UUID of the ruleset to retrieve

Query Parameters:

Parameter Description
version Optional specific version to retrieve (e.g., "1.0.0") 
curl -X GET "https://<your-instance>.aegis.pegasys.cloud/api/rulesets/uuid/6bc1814c-5705-5b6e-af99-104b91962282" \
  -H "Authorization: Bearer <your_token>"

{
  "name": "demo",
  "uuid": "6bc1814c-5705-5b6e-af99-104b91962282",
  "description": "Kubernetes deployment security rules",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "rules": [
    {
      "name": "enforce-app-label",
      "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p",
      "enforce": true,
      "dryrun": false
    }
  ],
  "version": "1.0.0",
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2025-06-01T10:00:00Z"
}

Create Ruleset

Create a new ruleset using natural language instructions.

POST /api/rulesets/{ruleset_name}

Path Parameters:

Parameter Description
ruleset_name The name of the ruleset to create

Request Body Fields:

Field Description
instruction.rule Natural language description of the rule to create
instruction.filter Filter criteria for resource selection
instruction.tag Optional tag for the rule
instruction.format Format of the input data. Valid formats are: hcl (for Terraform), dockerfile (for Docker), json (for Terraform Plan and custom), and yaml (for Kubernetes, CloudFormation, Cloud Build, Azure DevOps, GitLab CI, and GitHub Actions).
instruction.category Category of the resource. Valid categories are: docker, terraform, terraform-plan, cloudformation, azure-resource (for ARM templates), kubernetes, custom, gitlab-pipeline, github-actions, azure-devops.
instruction.type Specific resource type (e.g., "deployment", "aws_s3_bucket", "pod")
labels Key-value pairs for organizing and filtering rulesets 
curl -X POST "https://<your-instance>.aegis.pegasys.cloud/api/rulesets/demo" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/x-yaml" \
  -d @- <<EOF
            instruction:
              rule: ensure app label has a value
              filter: ensure that at least one resource of type Deployment is present
              tag: ''
              format: json
              category: kubernetes
              type: deployment
            labels:
              platform: kubernetes
              resource: deployment
        EOF

instruction:
  rule: ensure app label has a value
  filter: ensure that at least one resource of type Deployment is present
  tag: ''
  format: json
  category: kubernetes
  type: deployment
labels:
  platform: kubernetes
  resource: deployment

{
  "name": "demo",
  "uuid": "6bc1814c-5705-5b6e-af99-104b91962282",
  "description": "Ruleset for checking Kubernetes deployment app labels",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "rules": [
    {
      "name": "enforce-app-label",
      "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p",
      "description": "Ensures app label is present and has a value",
      "condition": "input.metadata.labels.app != null",
      "message": "Deployment must have an app label",
      "enforce": true,
      "dryrun": false
    }
  ],
  "version": "1.0.0",
  "createdAt": "2025-06-16T14:30:00Z"
}

Update Ruleset

Update an existing ruleset with additional rules using natural language instructions.

PUT /api/rulesets/{ruleset_name}

Path Parameters:

Parameter Description
ruleset_name The name of the ruleset to update

Request Body Fields:

Field Description
instruction.rule Natural language description of the rule to add or modify
instruction.filter Filter criteria for resource selection
instruction.tag Optional tag for the rule
instruction.format Format of the input data. Valid formats are: hcl (for Terraform), dockerfile (for Docker), json (for Terraform Plan and custom), and yaml (for Kubernetes, CloudFormation, Cloud Build, Azure DevOps, GitLab CI, and GitHub Actions).
instruction.category Category of the resource. Valid categories are: docker, terraform, terraform-plan, cloudformation, azure-resource (for ARM templates), kubernetes, custom, gitlab-pipeline, github-actions, azure-devops.
instruction.type Specific resource type (e.g., "deployment", "aws_s3_bucket", "pod") 
curl -X PUT "https://<your-instance>.aegis.pegasys.cloud/api/rulesets/demo" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/x-yaml" \
  -d @- <<EOF
          instruction:
            rule: add a rule to check if spec/replicas is > 3
            filter: ensure that at least one resource of type Deployment is present
            tag: ''
            format: json
            category: kubernetes
            type: deployment
      EOF

instruction:
  rule: add a rule to check if spec/replicas is > 3
  filter: ensure that at least one resource of type Deployment is present
  tag: ''
  format: json
  category: kubernetes
  type: deployment

{
  "name": "demo",
  "uuid": "6bc1814c-5705-5b6e-af99-104b91962282",
  "description": "Ruleset for checking Kubernetes deployment app labels",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "rules": [
    {
      "name": "enforce-app-label",
      "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p",
      "description": "Ensures app label is present and has a value",
      "condition": "input.metadata.labels.app != null",
      "message": "Deployment must have an app label",
      "enforce": true,
      "dryrun": false
    },
    {
      "name": "enforce-replicas-gt-3",
      "uuid": "c916e0b6-d5f7-482e-8b1e-069c14146bd6",
      "description": "Deployment must have at least 3 replicas for high availability",
      "condition": "input.spec.replicas > 3",
      "message": "Deployment replicas must be greater than 3",
      "enforce": true,
      "dryrun": false
    }
  ],
  "version": "1.0.1",
  "createdAt": "2025-06-16T14:30:00Z",
  "updatedAt": "2025-06-16T14:45:00Z"
}

Update Ruleset Properties

Update specific properties of a ruleset, including labels and rule enforcement settings.

PUT /api/rulesets/{ruleset_name}/props

Path Parameters:

Parameter Description
ruleset_name The name of the ruleset to update 
curl -X PUT "https://<your-instance>.aegis.pegasys.cloud/api/rulesets/demo/props" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
          {
            "labels": {
              "platform": "kubernetes",
              "resource": "deployment"
            },
            "rules": [
              {
                "name": "enforce-replicas-gt-3-non-test-policy",
                "uuid": "c916e0b6-d5f7-482e-8b1e-069c14146bd6",
                "enforce": true,
                "dryrun": false
              }
            ]
          }
      EOF

{
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "rules": [
    {
      "name": "enforce-replicas-gt-3-non-test-policy",
      "uuid": "c916e0b6-d5f7-482e-8b1e-069c14146bd6",
      "enforce": true,
      "dryrun": false
    }
  ]
}

{
  "name": "demo",
  "uuid": "6bc1814c-5705-5b6e-af99-104b91962282",
  "description": "Ruleset for checking Kubernetes deployment app labels",
  "labels": {
    "platform": "kubernetes",
    "resource": "deployment"
  },
  "rules": [
    {
      "name": "enforce-app-label",
      "uuid": "a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p",
      "description": "Ensures app label is present and has a value",
      "condition": "input.metadata.labels.app != null",
      "message": "Deployment must have an app label",
      "enforce": true,
      "dryrun": false
    },
    {
      "name": "enforce-replicas-gt-3-non-test-policy",
      "uuid": "c916e0b6-d5f7-482e-8b1e-069c14146bd6",
      "description": "Deployment must have at least 3 replicas for high availability",
      "condition": "input.spec.replicas > 3",
      "message": "Deployment replicas must be greater than 3",
      "enforce": true,
      "dryrun": false
    }
  ],
  "version": "1.0.2",
  "createdAt": "2025-06-16T14:30:00Z",
  "updatedAt": "2025-06-16T15:00:00Z"
}

Delete Ruleset

Delete a ruleset.

DELETE /api/rulesets/{ruleset_name}

Path Parameters:

Parameter Description
ruleset_name The name of the ruleset to delete 
curl -X DELETE "https://<your-instance>.aegis.pegasys.cloud/api/rulesets/demo" \
  -H "Authorization: Bearer <your_token>"

{
  "message": "Ruleset demo deleted successfully"
}

Evaluation

Evaluate Ruleset

Evaluate a ruleset against a provided input.

POST /api/eval/rulesets/{ruleset_name}

Path Parameters:

Parameter Description
ruleset_name The name of the ruleset to evaluate 
curl -X POST "https://<your-instance>.aegis.pegasys.cloud/api/eval/rulesets/demo" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
          {
            "inputData": {
              "apiVersion": "apps/v1",
              "kind": "Deployment",
              "metadata": {
                "name": "nginx",
                "namespace": "kube-app",
                "labels": {
                  "project": "nginx"
                }
              },
              "spec": {
                "replicas": 1
              }
            }
          }
      EOF

{
  "inputData": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "nginx",
      "namespace": "kube-app",
      "labels": {
        "project": "nginx"
      }
    },
    "spec": {
      "replicas": 1
    }
  }
}

{
  "ruleset": "demo",
  "passed": false,
  "results": [
    {
      "rule": "enforce-replicas-gt-3-non-test-policy",
      "status": "failed",
      "message": "Deployment must have at least 3 replicas for high availability"
    },
    {
      "rule": "enforce-app-label",
      "status": "failed",
      "message": "Deployment must have an app label"
    }
  ]
}