Share feedback
Answers are generated based on the documentation.
Product manualDownload OpenAPI specificationMarkdown

Create rule

POST/orgs/{org_name}/governance/policies/{policy_id}/rules

Adds a rule to the policy's rule set. All rules in a policy must share the same domain (network or filesystem); mixing domains is rejected.

Network actions: connect:tcp, connect:udp. Resources are hostnames (for example, example.com), wildcard subdomains (*.example.com for one level, **.example.com for any depth), hostnames with an optional port (for example, example.com:443), or CIDRs in IPv4 or IPv6 notation (for example, 10.0.0.0/8 or 2001:db8::/32).

Filesystem actions: read, write. Resources are paths (for example, /data). Use * to match within a single path segment and ** to match recursively across segments (for example, /data/**).

Changes may take up to five minutes to reach developer machines.

Connection and access

API connection and authentication guidance

https://hub.docker.com/v2

Use one of these alternatives. Requirements within an alternative apply together.

  • bearerAuth

Parameters

org_name path Required

Docker Hub organization name.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

policy_id path Required

Unique policy identifier.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

Request and responses

Request

Rule definition including actions, resources, and decision.

application/json

Schema: CreateRuleRequest

filesystem

{
  "actions": [
    "read",
    "write"
  ],
  "decision": "allow",
  "name": "allow data directory",
  "resources": [
    "/data"
  ]
}

network

{
  "actions": [
    "connect:tcp",
    "connect:udp"
  ],
  "decision": "allow",
  "name": "allow research mirrors",
  "resources": [
    "research.mitre.org",
    "cve.mitre.org"
  ]
}

Response 201

Rule created and added to the policy's rule set.

application/json

Schema: Rule

filesystem

{
  "actions": [
    "read",
    "write"
  ],
  "decision": "allow",
  "id": "rule_07fwtnr0kn2qetl1b9olfbyz8kob",
  "name": "allow data directory",
  "resources": [
    "/data"
  ]
}

network

{
  "actions": [
    "connect:tcp",
    "connect:udp"
  ],
  "decision": "allow",
  "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna",
  "name": "allow research mirrors",
  "resources": [
    "research.mitre.org",
    "cve.mitre.org"
  ]
}

Response 400

Bad request

application/json

Schema: Error

default

{
  "error": {
    "code": "invalid_argument",
    "message": "name is required"
  }
}

Response 401

Missing or invalid credentials

application/json

Schema: Error

default

{
  "error": {
    "code": "unauthenticated",
    "message": "unauthenticated"
  }
}

Response 403

Caller lacks the required permission for this org, the org is not entitled to use governance (permission_denied), or a creation limit has been reached (limit_exceeded): the org already has the maximum number of policies, or the policy already has the maximum number of rules.

application/json

Schema: Error

limit_exceeded

{
  "error": {
    "code": "limit_exceeded",
    "message": "organization has reached the maximum of 100 policies"
  }
}

permission_denied

{
  "error": {
    "code": "permission_denied",
    "message": "permission denied"
  }
}

Response 404

Not found

application/json

Schema: Error

default

{
  "error": {
    "code": "not_found",
    "message": "policy not found"
  }
}

Response 409

Conflict

application/json

Schema: Error

default

{
  "error": {
    "code": "conflict",
    "message": "policy name already in use"
  }
}

Response 500

Internal server error

application/json

Schema: Error

default

{
  "error": {
    "code": "internal",
    "message": "internal error"
  }
}

Referenced schemas

#/components/schemas/CreateRuleRequest

#/components/schemas/Rule

Complete operation contract
{
  "description": "Adds a rule to the policy's rule set. All rules in a policy must share\nthe same domain (network or filesystem); mixing domains is rejected.\n\n**Network** actions: `connect:tcp`, `connect:udp`. Resources are\nhostnames (for example, `example.com`), wildcard subdomains (`*.example.com`\nfor one level, `**.example.com` for any depth), hostnames with an optional\nport (for example, `example.com:443`), or CIDRs in IPv4 or IPv6 notation\n(for example, `10.0.0.0/8` or `2001:db8::/32`).\n\n**Filesystem** actions: `read`, `write`. Resources are paths (for example,\n`/data`). Use `*` to match within a single path segment and `**` to match\nrecursively across segments (for example, `/data/**`).\n\nChanges may take up to five minutes to reach developer machines.\n",
  "operationId": "createRule",
  "requestBody": {
    "content": {
      "application/json": {
        "examples": {
          "filesystem": {
            "summary": "Filesystem rule",
            "value": {
              "actions": [
                "read",
                "write"
              ],
              "decision": "allow",
              "name": "allow data directory",
              "resources": [
                "/data"
              ]
            }
          },
          "network": {
            "summary": "Network rule",
            "value": {
              "actions": [
                "connect:tcp",
                "connect:udp"
              ],
              "decision": "allow",
              "name": "allow research mirrors",
              "resources": [
                "research.mitre.org",
                "cve.mitre.org"
              ]
            }
          }
        },
        "schema": {
          "$ref": "#/components/schemas/CreateRuleRequest"
        }
      }
    },
    "description": "Rule definition including actions, resources, and decision.",
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "examples": {
            "filesystem": {
              "summary": "Filesystem rule",
              "value": {
                "actions": [
                  "read",
                  "write"
                ],
                "decision": "allow",
                "id": "rule_07fwtnr0kn2qetl1b9olfbyz8kob",
                "name": "allow data directory",
                "resources": [
                  "/data"
                ]
              }
            },
            "network": {
              "summary": "Network rule",
              "value": {
                "actions": [
                  "connect:tcp",
                  "connect:udp"
                ],
                "decision": "allow",
                "id": "rule_06evsm9qjm1pdsk0a8nkfaxy7jna",
                "name": "allow research mirrors",
                "resources": [
                  "research.mitre.org",
                  "cve.mitre.org"
                ]
              }
            }
          },
          "schema": {
            "$ref": "#/components/schemas/Rule"
          }
        }
      },
      "description": "Rule created and added to the policy's rule set."
    },
    "400": {
      "$ref": "#/components/responses/InvalidArgument"
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "summary": "Create rule",
  "tags": [
    "rules"
  ]
}