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, which includes HTTP, or filesystem); mixing domains is rejected. A single rule cannot mix L4 network and L7 HTTP actions.

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/**).

HTTP actions identify request methods, such as request:get and request:post. Use http_resources to identify the host, optional port, and absolute path glob. HTTP rules must not supply resources.

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, matching resources, and decision.

application/json

Schema: CreateRuleRequest

filesystem

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

http

{
  "actions": [
    "request:get",
    "request:head"
  ],
  "decision": "allow",
  "http_resources": [
    {
      "host": "api.github.com",
      "path": "/repos/docker/**",
      "port": 443
    }
  ],
  "name": "read GitHub repositories"
}

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"
  ]
}

http

{
  "actions": [
    "request:get",
    "request:head"
  ],
  "decision": "allow",
  "http_resources": [
    {
      "host": "api.github.com",
      "path": "/repos/docker/**",
      "port": 443
    }
  ],
  "id": "rule_08gxuos1lo3rfum2c0pmgcz09lpc",
  "name": "read GitHub repositories"
}

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`, which includes HTTP, or `filesystem`);\nmixing domains is rejected. A single rule cannot mix L4 network and L7\nHTTP actions.\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\n**HTTP** actions identify request methods, such as `request:get` and\n`request:post`. Use `http_resources` to identify the host, optional port,\nand absolute path glob. HTTP rules must not supply `resources`.\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"
              ]
            }
          },
          "http": {
            "summary": "HTTP rule",
            "value": {
              "actions": [
                "request:get",
                "request:head"
              ],
              "decision": "allow",
              "http_resources": [
                {
                  "host": "api.github.com",
                  "path": "/repos/docker/**",
                  "port": 443
                }
              ],
              "name": "read GitHub repositories"
            }
          },
          "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, matching 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"
                ]
              }
            },
            "http": {
              "summary": "HTTP rule",
              "value": {
                "actions": [
                  "request:get",
                  "request:head"
                ],
                "decision": "allow",
                "http_resources": [
                  {
                    "host": "api.github.com",
                    "path": "/repos/docker/**",
                    "port": 443
                  }
                ],
                "id": "rule_08gxuos1lo3rfum2c0pmgcz09lpc",
                "name": "read GitHub repositories"
              }
            },
            "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"
  ]
}