From 071f4ea99bd8333a6c69fe015ad5f50b58827d19 Mon Sep 17 00:00:00 2001 From: Charlie Egan Date: Tue, 3 Feb 2026 17:58:04 +0100 Subject: [PATCH] docs: Update broken links (#8285) * Update Regal documentation Sync documentation with upstream Regal repository to reflect latest changes. This addresses a number of broken link issues from the checker before. Signed-off-by: Charlie Egan * docs: Update release links these links create some issues in the link checker report. https://github.com/open-policy-agent/opa/issues/8278 ``` Errors in ./docs/docs/deploy/aws/ec2.mdx [404] https://github.com/open-policy-agent/opa/releases/download/v%7B%7Bversion%7D%7D/opa_linux_amd64 | Rejected status code (this depends on your "accept" configuration): Not Found Errors in ./docs/docs/deploy/azure/vm.mdx [404] https://github.com/open-policy-agent/opa/releases/download/v%7B%7Bversion%7D%7D/opa_linux_amd64 | Error (cached) Errors in ./docs/docs/deploy/google-cloud/gce.mdx [404] https://github.com/open-policy-agent/opa/releases/download/v%7B%7Bversion%7D%7D/opa_linux_amd64 | Error (cached) ``` These are not actually broken, they are just untemplated when the checker sees them. I figured since they are long lines we can use use a $REPO variable instead, to ensure that we only have valid https:// starting links on those pages. Signed-off-by: Charlie Egan * Remove broken blog link https://github.com/open-policy-agent/opa/issues/8278 this link appears to be gone with no redirect. Signed-off-by: Charlie Egan * docs: Fix outdated and broken documentation URLs Update various documentation links, SlideShare links, and external references that were resulting in redirects. Fixes https://github.com/open-policy-agent/opa/issues/8278 Signed-off-by: Charlie Egan * Update broken regal links The other rules are using abs links here. Signed-off-by: Charlie Egan --------- Signed-off-by: Charlie Egan --- README.md | 22 +++++++++--------- SECURITY.md | 2 +- docs/docs/contributing.md | 4 ++-- docs/docs/deploy/aws/ec2.mdx | 3 ++- docs/docs/deploy/azure/vm.mdx | 3 ++- docs/docs/deploy/google-cloud/gce.mdx | 3 ++- docs/docs/envoy/tutorial-gloo-edge.md | 2 +- .../unexpected-name-keyword.md | 2 +- docs/docs/faq.md | 2 +- docs/docs/integration.md | 2 +- docs/docs/kubernetes/debugging.md | 2 +- docs/docs/style-guide.md | 22 +++++++++--------- docs/projects/regal/adopters.md | 8 +++---- docs/projects/regal/custom-rules/index.md | 4 ++-- docs/projects/regal/custom-rules/roast.md | 18 +++++++++++++++ docs/projects/regal/fixing.md | 7 ++++-- docs/projects/regal/index.md | 1 + .../regal/rules/bugs/constant-condition.md | 2 ++ .../rules/bugs/redundant-existence-check.md | 2 ++ .../regal/rules/bugs/unused-return-value.md | 6 ++--- .../{style => custom}/chained-rule-body.md | 15 +++++++----- .../regal/rules/custom/disallow-rego-v1.md | 23 +++++++++++++++++++ .../rules/custom/prefer-value-in-head.md | 12 ++++++++-- .../idiomatic/directory-package-mismatch.md | 4 ++-- .../idiomatic/prefer-equals-comparison.md | 2 ++ docs/projects/regal/rules/style/messy-rule.md | 6 +++-- .../regal/rules/style/use-in-operator.md | 4 ++-- .../rules/testing/identically-named-tests.md | 2 +- docs/src/data/ecosystem/entries/alluxio.md | 2 +- .../data/ecosystem/entries/docker-machine.md | 2 +- .../entries/github-action-opa-rego-test.md | 2 +- .../ecosystem/entries/kafka-authorization.md | 4 ++-- docs/src/data/ecosystem/entries/oidc.md | 4 ++-- .../ecosystem/entries/principled-evolution.md | 3 --- proposals/attic/REGO_V2_PROPOSAL.md | 2 +- wasm/README.md | 2 +- 36 files changed, 135 insertions(+), 71 deletions(-) rename docs/projects/regal/rules/{style => custom}/chained-rule-body.md (66%) create mode 100644 docs/projects/regal/rules/custom/disallow-rego-v1.md diff --git a/README.md b/README.md index 981dc9a440..22bd72e24b 100644 --- a/README.md +++ b/README.md @@ -30,17 +30,17 @@ OPA is proud to be a graduated project in the [Cloud Native Computing Foundation ## Want to integrate OPA? -- See the high-level [Go SDK](https://www.openpolicyagent.org/docs/latest/integration/#integrating-with-the-go-sdk) or the low-level Go API - [![GoDoc](https://godoc.org/github.com/open-policy-agent/opa?status.svg)](https://godoc.org/github.com/open-policy-agent/opa/rego) +- See the high-level [Go SDK](https://www.openpolicyagent.org/docs/integration#integrating-with-the-go-sdk) or the low-level Go API + [![GoDoc](https://pkg.go.dev/badge/github.com/open-policy-agent/opa?utm_source=godoc)](https://pkg.go.dev/github.com/open-policy-agent/opa/rego?utm_source=godoc) to integrate OPA with services written in Go. - See the [REST API](https://www.openpolicyagent.org/docs/rest-api.html) reference to integrate OPA with services written in other languages. -- See the [integration docs](https://www.openpolicyagent.org/docs/latest/integration/) for more options. +- See the [integration docs](https://www.openpolicyagent.org/docs/integration) for more options. ## Want to contribute to OPA? -- Read the [Contributing Guide](https://www.openpolicyagent.org/docs/latest/contributing/) to learn how to make your first contribution. -- Use [#contributors](https://openpolicyagent.slack.com/archives/C02L1TLPN59) in Slack to talk to other contributors and OPA maintainers. +- Read the [Contributing Guide](https://www.openpolicyagent.org/docs/contributing) to learn how to make your first contribution. +- Use [#contributors](https://openpolicyagent.slack.com/?redir=%2Farchives%2FC02L1TLPN59%3Fname%3DC02L1TLPN59) in Slack to talk to other contributors and OPA maintainers. - File a [GitHub Issue](https://github.com/open-policy-agent/opa/issues) to request features or report bugs. ## How does OPA work? @@ -87,12 +87,12 @@ and more, see [openpolicyagent.org](https://www.openpolicyagent.org). - Open Policy Agent Intro @ KubeCon EU 2021: [Video](https://www.youtube.com/watch?v=2CgeiWkliaw) - Using Open Policy Agent to Meet Evolving Policy Requirements @ KubeCon NA 2020: [video](https://www.youtube.com/watch?v=zVuM7F_BTyc) - Applying Policy Throughout The Application Lifecycle with Open Policy Agent @ CloudNativeCon 2019: [video](https://www.youtube.com/watch?v=cXfsaE6RKfc) -- Open Policy Agent Introduction @ CloudNativeCon EU 2018: [video](https://youtu.be/XEHeexPpgrA), [slides](https://www.slideshare.net/TorinSandall/opa-the-cloud-native-policy-engine) -- Rego Deep Dive @ CloudNativeCon EU 2018: [video](https://youtu.be/4mBJSIhs2xQ), [slides](https://www.slideshare.net/TorinSandall/rego-deep-dive) -- How Netflix Is Solving Authorization Across Their Cloud @ CloudNativeCon US 2017: [video](https://www.youtube.com/watch?v=R6tUNpRpdnY), [slides](https://www.slideshare.net/TorinSandall/how-netflix-is-solving-authorization-across-their-cloud). -- Policy-based Resource Placement in Kubernetes Federation @ LinuxCon Beijing 2017: [slides](https://www.slideshare.net/TorinSandall/policybased-resource-placement-across-hybrid-cloud), [screencast](https://www.youtube.com/watch?v=hRz13baBhfg&feature=youtu.be) -- Enforcing Bespoke Policies In Kubernetes @ KubeCon US 2017: [video](https://www.youtube.com/watch?v=llDI8VvkUj8), [slides](https://www.slideshare.net/TorinSandall/enforcing-bespoke-policies-in-kubernetes) -- Istio's Mixer: Policy Enforcement with Custom Adapters @ CloudNativeCon US 2017: [video](https://www.youtube.com/watch?v=czZLXUqzd24), [slides](https://www.slideshare.net/TorinSandall/istios-mixer-policy-enforcement-with-custom-adapters-cloud-nativecon-17) +- Open Policy Agent Introduction @ CloudNativeCon EU 2018: [video](https://youtu.be/XEHeexPpgrA), [slides](https://www.slideshare.net/slideshow/opa-the-cloud-native-policy-engine/96644504) +- Rego Deep Dive @ CloudNativeCon EU 2018: [video](https://youtu.be/4mBJSIhs2xQ), [slides](https://www.slideshare.net/slideshow/rego-deep-dive/96644608) +- How Netflix Is Solving Authorization Across Their Cloud @ CloudNativeCon US 2017: [video](https://www.youtube.com/watch?v=R6tUNpRpdnY), [slides](https://www.slideshare.net/slideshow/how-netflix-is-solving-authorization-across-their-cloud/84384095). +- Policy-based Resource Placement in Kubernetes Federation @ LinuxCon Beijing 2017: [slides](https://www.slideshare.net/slideshow/policybased-resource-placement-across-hybrid-cloud/83876901), [screencast](https://www.youtube.com/watch?v=hRz13baBhfg&feature=youtu.be) +- Enforcing Bespoke Policies In Kubernetes @ KubeCon US 2017: [video](https://www.youtube.com/watch?v=llDI8VvkUj8), [slides](https://www.slideshare.net/slideshow/enforcing-bespoke-policies-in-kubernetes/83877237) +- Istio's Mixer: Policy Enforcement with Custom Adapters @ CloudNativeCon US 2017: [video](https://www.youtube.com/watch?v=czZLXUqzd24), [slides](https://www.slideshare.net/slideshow/istios-mixer-policy-enforcement-with-custom-adapters-cloud-nativecon-17/83877455) ## Security diff --git a/SECURITY.md b/SECURITY.md index d90b7e962f..ffc1340700 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,5 @@ # Security Policy -Please refer to the [OPA Security Policy](https://openpolicyagent.org/security) +Please refer to the [OPA Security Policy](https://www.openpolicyagent.org/security) for details on how to report security issues, our disclosure policy, and how to receive notifications about security issues. \ No newline at end of file diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index 838fbc4d34..551b0e7e98 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -14,7 +14,7 @@ you can [sign up here](https://slack.openpolicyagent.org/). ## I'd like to help OPA users -Most users ask in the [#help](https://openpolicyagent.slack.com/archives/CBR63TK2A) +Most users ask in the [#help](https://openpolicyagent.slack.com/?redir=%2Farchives%2FCBR63TK2A%3Fname%3DCBR63TK2A) channel in Slack, hang out in there and see if there are any questions you can help with. @@ -68,7 +68,7 @@ to have your project listed on the ecosystem page. If you have a talk or blog you'd like to share please feel free to post in: -- [#ecosystem](https://openpolicyagent.slack.com/archives/C02J6LBL6GH) in Slack. +- [#ecosystem](https://openpolicyagent.slack.com/?redir=%2Farchives%2FC02J6LBL6GH%3Fname%3DC02J6LBL6GH) in Slack. - [Ecosystem Discussions](https://github.com/orgs/open-policy-agent/discussions/categories/ecosystem) on GitHub. ## I'm interested in something else... diff --git a/docs/docs/deploy/aws/ec2.mdx b/docs/docs/deploy/aws/ec2.mdx index 99bc14baba..c6742e8111 100644 --- a/docs/docs/deploy/aws/ec2.mdx +++ b/docs/docs/deploy/aws/ec2.mdx @@ -121,7 +121,8 @@ Please use the user data shell script below to install and run OPA: {`#!/bin/bash -curl -L -o /usr/local/bin/opa https://github.com/open-policy-agent/opa/releases/download/v{{version}}/opa_linux_amd64 +REPO=https://github.com/open-policy-agent/opa +curl -L -o /usr/local/bin/opa $REPO/releases/download/v{{version}}/opa_linux_amd64 chmod 755 /usr/local/bin/opa cat < /etc/credstore/opa.service/config diff --git a/docs/docs/deploy/azure/vm.mdx b/docs/docs/deploy/azure/vm.mdx index 195acb9a3a..f7cbda2c57 100644 --- a/docs/docs/deploy/azure/vm.mdx +++ b/docs/docs/deploy/azure/vm.mdx @@ -113,7 +113,8 @@ Please use the user data shell script below to install and run OPA: {`#!/bin/bash -curl -L -o /usr/local/bin/opa https://github.com/open-policy-agent/opa/releases/download/v{{version}}/opa_linux_amd64 +REPO=https://github.com/open-policy-agent/opa +curl -L -o /usr/local/bin/opa $REPO/releases/download/v{{version}}/opa_linux_amd64 chmod 755 /usr/local/bin/opa cat < /etc/credstore/opa.service/config diff --git a/docs/docs/deploy/google-cloud/gce.mdx b/docs/docs/deploy/google-cloud/gce.mdx index 9ff31c6207..96d2931621 100644 --- a/docs/docs/deploy/google-cloud/gce.mdx +++ b/docs/docs/deploy/google-cloud/gce.mdx @@ -128,7 +128,8 @@ Please use the user data shell script below to install and run OPA: {`#!/bin/bash -curl -L -o /usr/local/bin/opa https://github.com/open-policy-agent/opa/releases/download/v{{version}}/opa_linux_amd64 +REPO=https://github.com/open-policy-agent/opa +curl -L -o /usr/local/bin/opa $REPO/releases/download/v{{version}}/opa_linux_amd64 chmod 755 /usr/local/bin/opa cat < /etc/credstore/opa.service/config diff --git a/docs/docs/envoy/tutorial-gloo-edge.md b/docs/docs/envoy/tutorial-gloo-edge.md index 338d5c1c10..4c5b6a2472 100644 --- a/docs/docs/envoy/tutorial-gloo-edge.md +++ b/docs/docs/envoy/tutorial-gloo-edge.md @@ -5,7 +5,7 @@ sidebar_position: 4 [Gloo Edge](https://docs.solo.io/gloo-edge/latest/) is an Envoy based API Gateway that provides a Kubernetes CRD to manage Envoy configuration for performing traffic management and routing. -Gloo Edge allows creation of a [Custom External Auth Service](https://docs.solo.io/gloo-edge/master/guides/security/auth/custom_auth/) that implements the Envoy spec for an [External Authorization Server](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/ext_authz_filter.html). +Gloo Edge allows creation of a [Custom External Auth Service](https://docs.solo.io/gloo-edge/latest/guides/security/opa/) that implements the Envoy spec for an [External Authorization Server](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/ext_authz_filter.html). The purpose of this tutorial is to show how OPA could be used with Gloo Edge to apply security policies for upstream services. diff --git a/docs/docs/errors/rego-parse-error/unexpected-name-keyword.md b/docs/docs/errors/rego-parse-error/unexpected-name-keyword.md index 283185c71a..6b45b2e73a 100644 --- a/docs/docs/errors/rego-parse-error/unexpected-name-keyword.md +++ b/docs/docs/errors/rego-parse-error/unexpected-name-keyword.md @@ -58,4 +58,4 @@ A common cause for such misunderstandings is expressing or in Rego, if you think [blog post](https://www.styra.com/blog/how-to-express-or-in-rego/) on this topic here you might want to check out. Failing that, the best place to start is to review the OPA documentation on Rego, see this page for an -[explanation of Rego's keywords](https://www.openpolicyagent.org/docs/policy-language/). +[explanation of Rego's keywords](https://www.openpolicyagent.org/docs/policy-language). diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 1e18226fd5..3577dd7f6b 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -314,7 +314,7 @@ not p[x] ## JSON Web Tokens (JWTs) -[JSON Web Tokens (JWTs)](https://jwt.io/) are an industry standard for exchanging information between services. Often they are used to represent information about the users logged into a system. OPA has special-purpose code for dealing with JWTs. +[JSON Web Tokens (JWTs)](https://www.jwt.io/) are an industry standard for exchanging information between services. Often they are used to represent information about the users logged into a system. OPA has special-purpose code for dealing with JWTs. All JWTs with OPA come in as strings. That string is a JSON Web Token encoded with JWS Compact Serialization. JWE and JWS JSON Serialization are not supported. diff --git a/docs/docs/integration.md b/docs/docs/integration.md index 30b59a5c56..eab53c4e14 100644 --- a/docs/docs/integration.md +++ b/docs/docs/integration.md @@ -262,7 +262,7 @@ func main() { } ``` -If you executed this code, the output (i.e. [Decision Log](https://www.openpolicyagent.org/docs/latest/management-decision-logs/) event) +If you executed this code, the output (i.e. [Decision Log](https://www.openpolicyagent.org/docs/management-decision-logs) event) would be logged to the console by default. Setting an `ID` in `sdk.Options` is optional, but recommended. If you do not set an `ID`, a random one will be created diff --git a/docs/docs/kubernetes/debugging.md b/docs/docs/kubernetes/debugging.md index cfd297edb9..b23170c706 100644 --- a/docs/docs/kubernetes/debugging.md +++ b/docs/docs/kubernetes/debugging.md @@ -8,7 +8,7 @@ configured correctly. If none of these tips work, feel free to join [our slack](https://slack.openpolicyagent.org) and ask for help. The tips below cover the OPA-Kubernetes integration that uses kube-mgmt. -The [OPA Gatekeeper version](https://open-policy-agent.github.io/gatekeeper) +The [OPA Gatekeeper version](https://open-policy-agent.github.io/gatekeeper/) has its own docs. ### Check for the `openpolicyagent.org/kube-mgmt-status` annotation on ConfigMaps containing policies diff --git a/docs/docs/style-guide.md b/docs/docs/style-guide.md index a405b55782..960edc5bf1 100644 --- a/docs/docs/style-guide.md +++ b/docs/docs/style-guide.md @@ -7,7 +7,7 @@ sidebar_label: Style Guide The purpose of this style guide is to provide a collection of recommendations and best practices for authoring -[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/). +[Rego](https://www.openpolicyagent.org/docs/policy-language). From the maintainers of [Open Policy Agent](https://www.openpolicyagent.org) (OPA), and some of the most experienced members of the community, we hope to share lessons learnt from authoring and reviewing hundreds of thousands of lines of Rego over the years. @@ -36,7 +36,7 @@ the problem at hand. #### Related Resources -- [Policy Performance](https://www.openpolicyagent.org/docs/latest/policy-performance/) +- [Policy Performance](https://www.openpolicyagent.org/docs/policy-performance) ### Use `opa fmt` @@ -79,7 +79,7 @@ pipeline. ### Use metadata annotations -Favor [metadata annotations](https://www.openpolicyagent.org/docs/latest/policy-language/#metadata) over regular comments. +Favor [metadata annotations](https://www.openpolicyagent.org/docs/policy-language#metadata) over regular comments. Metadata annotations allow external tools and editors to parse their contents, potentially leveraging them for something useful, like in-line explanations, generated docs, etc. @@ -142,7 +142,7 @@ Use regular comments inside of rule bodies, or for packages and rules you consid #### Related Resources -- [Annotations](https://www.openpolicyagent.org/docs/latest/policy-language/#metadata) +- [Annotations](https://www.openpolicyagent.org/docs/policy-language#metadata) ### Get to know the built-in functions @@ -289,8 +289,8 @@ if encountering undefined in a rule is likely desirable, this doesn't hold true i.e. rules like `deny` (as opposed to `allow`). Saying `deny is undefined` or `deny is false` if undefined is encountered, essentially means that any occurrence of undefined (such as when attributes are missing in the input document) would lead to the `deny` rule not getting enforced. This is particularly common writing partial rules (i.e. -rules that build [sets](https://www.openpolicyagent.org/docs/latest/policy-language/#generating-sets) or -[objects](https://www.openpolicyagent.org/docs/latest/policy-language/#generating-objects)). +rules that build [sets](https://www.openpolicyagent.org/docs/policy-language#generating-sets) or +[objects](https://www.openpolicyagent.org/docs/policy-language#generating-objects)). Consider for example this simple rule: @@ -329,7 +329,7 @@ cases covered. #### Related Resources -- [OPA AWS CloudFormation Hook Tutorial](https://www.openpolicyagent.org/docs/latest/aws-cloudformation-hooks/) +- [OPA AWS CloudFormation Hook Tutorial](https://www.openpolicyagent.org/docs/aws-cloudformation-hooks) ### Consider partial helper rules over comprehensions in rule bodies @@ -618,7 +618,7 @@ This function has been deprecated for a long time, and will eventually be remove ### Don't use unification operator for assignment or comparison -The [unification](https://www.openpolicyagent.org/docs/latest/policy-language/#unification-) operator (`=`) allows you +The [unification](https://www.openpolicyagent.org/docs/policy-language#unification-) operator (`=`) allows you to combine assignment and comparison. While this is useful in a few specific cases (see "Notes / Exceptions" below), using the assignment operator (`:=`) for assignment, and the comparison operator (`==`) for comparison, is almost always preferable. Separating assignment from comparison clearly demonstrates intent, and removes the ambiguity around scope @@ -796,7 +796,7 @@ allow if { #### Related Resources -- [Five things you didn't know about OPA](https://www.styra.com/blog/five-things-you-didnt-know-about-opa). +- [Five things you didn't know about OPA](https://www.styra.com/blog/five-things-you-didnt-know-about-opa/). ## Functions @@ -835,7 +835,7 @@ is_preferred_login_method(method, user, all_login_methods) if { Older Rego policies sometimes contain an unusual way to declare where the return value of a function call should be stored — the last argument of the function. True to it's -[Datalog](https://www.openpolicyagent.org/docs/latest/policy-language/#what-is-rego) roots, return values may be stored +[Datalog](https://www.openpolicyagent.org/docs/policy-language#what-is-rego) roots, return values may be stored either using assignment (i.e. `:=`) or by appending a variable name to the argument list of a function. These two expressions are thus equivalent: @@ -1034,7 +1034,7 @@ of completeness, and to provide context for older policies. **With the introduction of the `import rego.v1` construct in OPA v0.59.0, this is no longer needed** In order to evolve the Rego language without breaking existing policies, many new features require importing -["future" keywords](https://www.openpolicyagent.org/docs/latest/policy-language/#future-keywords), like `contains`, +["future" keywords](https://www.openpolicyagent.org/docs/policy-language#future-keywords), like `contains`, `every`, `if` and `in`. While it might seem convenient to use the "catch-all" form of `import future.keywords` to import all of the future keywords, this construct risks breaking your policies when new keywords are introduced, and their names happen to collide with names you've used for variables or rules. diff --git a/docs/projects/regal/adopters.md b/docs/projects/regal/adopters.md index 4e5c57a080..bf18b96cac 100644 --- a/docs/projects/regal/adopters.md +++ b/docs/projects/regal/adopters.md @@ -60,7 +60,7 @@ The following package managers include Regal in their repositories, either nativ - [mise](https://mise.jdx.dev/) via its [aqua](https://aquaproj.github.io/) backend and [aqua's regal definition](https://github.com/aquaproj/aqua-registry/tree/main/pkgs/open-policy-agent/regal) - [pkgsrc](https://www.pkgsrc.se/) and the [regal](https://pkgsrc.se/devel/regal) package - [Nix](https://nixos.org/): [regal](https://search.nixos.org/packages?channel=24.05&show=regal&from=0&size=50&sort=relevance&type=packages&query=regal) -- [mason.vim](https://github.com/mason-org/mason.nvim): [regal](https://github.com/mason-org/mason-registry/blob/main/packages/regal/package.yaml) +- [mason.vim](https://github.com/williamboman/mason.nvim): [regal](https://github.com/mason-org/mason-registry/blob/main/packages/regal/package.yaml) ## Companies and Organizations @@ -74,12 +74,12 @@ Some companies and organizations using Regal. - [CISA](https://www.cisa.gov) - [Elastic](https://www.elastic.co) - [Google](https://www.google.com) -- [Microsoft](https://www.microsoft.com/en-us/) +- [Microsoft](https://www.microsoft.com) - [Ministry of Justice](https://www.gov.uk/government/organisations/ministry-of-justice) - [Miro](https://miro.com) - [OpenCV](https://opencv.org) -- [Red Hat](https://www.redhat.com/en) -- [Spacelift](https://spacelift.io/) +- [Red Hat](https://www.redhat.com) +- [Spacelift](https://www.spacelift.io) - [Stacklok](https://stacklok.com) - [Styra](https://www.styra.com) - [UNIwise](https://uniwise.eu/) diff --git a/docs/projects/regal/custom-rules/index.md b/docs/projects/regal/custom-rules/index.md index ea7c310d14..b83f49b0d4 100644 --- a/docs/projects/regal/custom-rules/index.md +++ b/docs/projects/regal/custom-rules/index.md @@ -298,10 +298,10 @@ aggregate contains entry if { # if found, collect the result into our aggregate collection # we don't really need the location here, but showing for demonstration - entry := result.aggregate(rego.metadata.chain(), { + entry := { # optional metadata here "package": input.package, - }) + } } # METADATA diff --git a/docs/projects/regal/custom-rules/roast.md b/docs/projects/regal/custom-rules/roast.md index 0fbd14dbbf..8406f9511d 100644 --- a/docs/projects/regal/custom-rules/roast.md +++ b/docs/projects/regal/custom-rules/roast.md @@ -216,6 +216,24 @@ The `name` attribute found in the OPA AST for `rules` is unreliable, as it's not attribute however always is. While this doesn't come with any real cost in terms of AST size or performance, consistency is key. +### Added `interpolated` boolean attribute to template string expression nodes + +Expressions found in template strings (like `$"{upper(input.name)}"`) are normal expressions as far as OPA is concerned. +While that may be true, some linter rules targeted at "normal" expressions aren't applicable for expressions found +in template strings. Take for example the +[unassigned-return-value](https://www.openpolicyagent.org/projects/regal/rules/bugs/unassigned-return-value) rule, which +would normally consider an expression like `upper(input.name)` to be a bug, as the return value of the `upper` call +never is assigned. This is not the case for expressions found in template strings, as the output of their expressions +is used to build the interpolated string. In order to avoid traversing the module tree twice — once for regular +expressions, and once for expressions found in template strings — the Roast format instead marks expressions +template strings with an `interpolated` boolean attribute set to `true`. This attribute is only present for +expressions found in template strings, and is thus either `true` or missing, never `false`. + +### Template string `multi_line` attribute only present when `true` + +Following the Roast convention of omitting boolean attributes that are `false`, the `multi_line` attribute found +on template string nodes is only present when `true`. + ### Fixed inconsistencies in the original Rego AST A few inconsistencies exist in the original AST JSON format: diff --git a/docs/projects/regal/fixing.md b/docs/projects/regal/fixing.md index e5e667d756..21c8034d9e 100644 --- a/docs/projects/regal/fixing.md +++ b/docs/projects/regal/fixing.md @@ -31,6 +31,9 @@ Currently, the following rules are automatically fixable: - [use-assignment-operator](https://www.openpolicyagent.org/projects/regal/rules/style/use-assignment-operator) - [no-whitespace-comment](https://www.openpolicyagent.org/projects/regal/rules/style/no-whitespace-comment) - [directory-package-mismatch](https://www.openpolicyagent.org/projects/regal/rules/idiomatic/directory-package-mismatch) +- [prefer-equals-comparison](https://www.openpolicyagent.org/projects/regal/rules/idiomatic/prefer-equals-comparison) +- [redundant-existence-check](https://www.openpolicyagent.org/projects/regal/rules/bugs/redundant-existence-check) +- [constant-condition](https://www.openpolicyagent.org/projects/regal/rules/bugs/constant-condition) - [use-rego-v1](https://www.openpolicyagent.org/projects/regal/rules/imports/use-rego-v1) (v0 Rego only) So, how do you go on about automatically fixing reported violations? @@ -109,6 +112,6 @@ Compared to `regal fix`, automatically fixing violations in editors has some lim changes made. :::tip -If you're curious about using Regal to fix problems directly in your editor, see the docs on editor support -[here](https://www.openpolicyagent.org/projects/regal/editor-support) to learn more! +If you're curious about using Regal to fix problems directly in your editor, see the docs on +[Regal's editor support](https://www.openpolicyagent.org/projects/regal/editor-support) to learn more! ::: diff --git a/docs/projects/regal/index.md b/docs/projects/regal/index.md index ab41515774..3a6aee1c12 100644 --- a/docs/projects/regal/index.md +++ b/docs/projects/regal/index.md @@ -279,3 +279,4 @@ The current Roadmap items are all related to the preparation for - [lsp: Support a JetBrains LSP client (#1560)](https://github.com/open-policy-agent/regal/issues/1560) If there's something you'd like to have added to the roadmap, either open an issue, or reach out in the community Slack! + diff --git a/docs/projects/regal/rules/bugs/constant-condition.md b/docs/projects/regal/rules/bugs/constant-condition.md index 70b7ac2db4..4661561716 100644 --- a/docs/projects/regal/rules/bugs/constant-condition.md +++ b/docs/projects/regal/rules/bugs/constant-condition.md @@ -4,6 +4,8 @@ **Category**: Bugs +**Automatically fixable**: [Yes](https://www.openpolicyagent.org/projects/regal/fixing) + **Avoid** ```rego package policy diff --git a/docs/projects/regal/rules/bugs/redundant-existence-check.md b/docs/projects/regal/rules/bugs/redundant-existence-check.md index 9ebbb9253f..c21e2bbf68 100644 --- a/docs/projects/regal/rules/bugs/redundant-existence-check.md +++ b/docs/projects/regal/rules/bugs/redundant-existence-check.md @@ -4,6 +4,8 @@ **Category**: Bugs +**Automatically fixable**: [Yes](https://www.openpolicyagent.org/projects/regal/fixing) + **Avoid** ```rego package policy diff --git a/docs/projects/regal/rules/bugs/unused-return-value.md b/docs/projects/regal/rules/bugs/unused-return-value.md index a0a5e2b005..aab5d4f836 100644 --- a/docs/projects/regal/rules/bugs/unused-return-value.md +++ b/docs/projects/regal/rules/bugs/unused-return-value.md @@ -1,10 +1,10 @@ --- draft: true ---- +--- # unused-return-value ## Please Note -This rule has been renamed to *unassigned-return-value* and can be found -[here](https://www.openpolicyagent.org/projects/regal/rules/bugs/unassigned-return-value). +This rule has been renamed to +[_unassigned-return-value_](https://www.openpolicyagent.org/projects/regal/rules/bugs/unassigned-return-value). diff --git a/docs/projects/regal/rules/style/chained-rule-body.md b/docs/projects/regal/rules/custom/chained-rule-body.md similarity index 66% rename from docs/projects/regal/rules/style/chained-rule-body.md rename to docs/projects/regal/rules/custom/chained-rule-body.md index c746ffef74..f67923e585 100644 --- a/docs/projects/regal/rules/style/chained-rule-body.md +++ b/docs/projects/regal/rules/custom/chained-rule-body.md @@ -2,7 +2,7 @@ **Summary**: Avoid chaining rule bodies -**Category**: Style +**Category**: Custom **Avoid** ```rego @@ -36,9 +36,8 @@ understood by people new to Rego. ## Exceptions -The `opa fmt` command will automatically "unchain" chained rule bodies, so if you have enabled the [opa-fmt](opa-fmt) -rule, you may safely configure the level of this rule to `ignore`. While we normally don't include style rules covered -by `opa fmt`, this one is peculiar enough that we felt it was worthy of an exception. +The `opa fmt` command will automatically "unchain" chained rule bodies, so if you have enabled the [opa-fmt](https://www.openpolicyagent.org/projects/regal/rules/style/opa-fmt) +rule (as it is by default), there's no point in enabling this rule. ## Configuration Options @@ -46,8 +45,12 @@ This linter rule provides the following configuration options: ```yaml rules: - style: + custom: chained-rule-body: + # note that all rules in the "custom" category are disabled by default + # (i.e. level "ignore") as some configuration needs to be provided by + # the user (i.e. you!) in order for them to be useful. + # # one of "error", "warning", "ignore" level: error ``` @@ -55,4 +58,4 @@ rules: ## Related Resources - OPA Docs: [Incremental Definitions](https://www.openpolicyagent.org/docs/policy-language/#incremental-definitions) -- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/style/chained-rule-body/chained_rule_body.rego) +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/custom/chained-rule-body/chained_rule_body.rego) diff --git a/docs/projects/regal/rules/custom/disallow-rego-v1.md b/docs/projects/regal/rules/custom/disallow-rego-v1.md new file mode 100644 index 0000000000..0834df66ab --- /dev/null +++ b/docs/projects/regal/rules/custom/disallow-rego-v1.md @@ -0,0 +1,23 @@ +# disallow-rego-v1 + +**Summary**: Use of disallowed `import rego v1` + +**Category**: Custom + +## Rationale + +Since OPA v1.0, the `rego.v1` import is effectively a no-op. As such, this rule serves as a way for teams to +keep this import from popping up in code when it is no longer needed. Also, because this import is still +needed to evaluate policy for older OPA versions, this rule serves as a way to ensure older versions of +OPA (any prior to v1.0) are not being used. + +## Note + +This rule is intended to be enabled for projects that have been configured to target versions of OPA from 1.0 +onwards, but Regal does not explicitly check which version of OPA is being targeted for this rule. If working +with older versions of OPA and Rego, you probably don't want to enable this rule. + +## Related Resources + +- GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/custom/disallow-rego-v1/disallow_rego_v1.rego) +- OPA Docs: [Imports](https://www.openpolicyagent.org/docs/policy-language/#imports) diff --git a/docs/projects/regal/rules/custom/prefer-value-in-head.md b/docs/projects/regal/rules/custom/prefer-value-in-head.md index 5d1823ecd3..674823bc1c 100644 --- a/docs/projects/regal/rules/custom/prefer-value-in-head.md +++ b/docs/projects/regal/rules/custom/prefer-value-in-head.md @@ -5,6 +5,7 @@ **Category**: Custom **Avoid** + ```rego package policy @@ -20,6 +21,7 @@ deny contains message if { ``` **Prefer** + ```rego package policy @@ -58,6 +60,9 @@ deny contains message if { } ``` +The `include-interpolated` configuration option may be used to count interpolated strings as a scalar (string) values, +which will have Regal recommend moving them to the head even when `only-scalars` is set to `true`. + ## Configuration Options This linter rule provides the following configuration options: @@ -74,10 +79,13 @@ rules: # whether to only suggest moving scalar values (strings, numbers, booleans, null) # to the head, and not expressions or functions only-scalars: false + # when set to true, counts interpolated strings as a scalar value, and will suggest + # moving them to the head even when `only-scalars` is true + include-interpolated: false # variable names to exempt from the rule (by default, none) except-var-names: - - report - - violation + - report + - violation ``` ## Related Resources diff --git a/docs/projects/regal/rules/idiomatic/directory-package-mismatch.md b/docs/projects/regal/rules/idiomatic/directory-package-mismatch.md index de641a3b2f..4a27b9d5b1 100644 --- a/docs/projects/regal/rules/idiomatic/directory-package-mismatch.md +++ b/docs/projects/regal/rules/idiomatic/directory-package-mismatch.md @@ -78,7 +78,7 @@ Whichever way you choose is up to you. Consistency is key! ### Bundles While directory structure doesn't matter to OPA when parsing _policies_, directories parsed as -[bundles](https://www.openpolicyagent.org/docs/management-bundles/) will read _data_ (`data.json` or +[bundles](https://www.openpolicyagent.org/docs/management-bundles) will read _data_ (`data.json` or `data.yaml`) files and insert the data in the `data` document tree based on the directory structure relative to the bundle root. Having policies structured in the same manner provides a uniform experience, and makes it easier to understand where both policies and data come from. @@ -133,5 +133,5 @@ rules: - Rego Style Guide: [Package name should match file location](https://www.openpolicyagent.org/docs/style-guide#package-name-should-match-file-location) - Regal Docs: [test-outside-test-package](https://www.openpolicyagent.org/projects/regal/rules/testing/test-outside-test-package) -- OPA Docs: [Bundles](https://www.openpolicyagent.org/docs/management-bundles/) +- OPA Docs: [Bundles](https://www.openpolicyagent.org/docs/management-bundles) - GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/idiomatic/directory-package-mismatch/directory_package_mismatch.rego) diff --git a/docs/projects/regal/rules/idiomatic/prefer-equals-comparison.md b/docs/projects/regal/rules/idiomatic/prefer-equals-comparison.md index 964c9f707e..56aedfd0fc 100644 --- a/docs/projects/regal/rules/idiomatic/prefer-equals-comparison.md +++ b/docs/projects/regal/rules/idiomatic/prefer-equals-comparison.md @@ -4,6 +4,8 @@ **Category**: Idiomatic +**Automatically fixable**: [Yes](https://www.openpolicyagent.org/projects/regal/fixing) + **Avoid** ```rego package policy diff --git a/docs/projects/regal/rules/style/messy-rule.md b/docs/projects/regal/rules/style/messy-rule.md index c1c00e3061..9aad19002d 100644 --- a/docs/projects/regal/rules/style/messy-rule.md +++ b/docs/projects/regal/rules/style/messy-rule.md @@ -11,11 +11,11 @@ package policy allow if something -unrelated_rule if { +unrelated_rule if { # <--- this rule is breaking up allow # ... } -allow if something_else +allow if something_else # <--- should be with the first allow ``` **Prefer** @@ -34,6 +34,8 @@ unrelated_rule if { ## Rationale +In Rego, rules can can be formed of many 'rule heads', partial definitions +covering specific cases which together make up the behaviour of the whole rule. Rules that are defined incrementally should have their definitions grouped together, as this makes the code easier to follow. While this is mostly a style preference, having incremental rules grouped also allows editors like VS Code to "know" that the rules belong together, allowing them to be smarter when displaying the symbols of a workspace. diff --git a/docs/projects/regal/rules/style/use-in-operator.md b/docs/projects/regal/rules/style/use-in-operator.md index 662e738b29..e12a43e150 100644 --- a/docs/projects/regal/rules/style/use-in-operator.md +++ b/docs/projects/regal/rules/style/use-in-operator.md @@ -2,5 +2,5 @@ ## Please Note -This rule has been moved to *idiomatic* category and can be found -[here](https://www.openpolicyagent.org/projects/regal/rules/idiomatic/use-in-operator). +This rule has been moved to the +[_idiomatic_ category](https://www.openpolicyagent.org/projects/regal/rules/idiomatic/use-in-operator). diff --git a/docs/projects/regal/rules/testing/identically-named-tests.md b/docs/projects/regal/rules/testing/identically-named-tests.md index 9592869bde..4056e31195 100644 --- a/docs/projects/regal/rules/testing/identically-named-tests.md +++ b/docs/projects/regal/rules/testing/identically-named-tests.md @@ -54,6 +54,6 @@ rules: ## Related Resources -- OPA Docs: [Policy Testing](https://www.openpolicyagent.org/docs/policy-testing/) +- OPA Docs: [Policy Testing](https://www.openpolicyagent.org/docs/policy-testing) - OPA GitHub: [Support running of individual test rules sharing same name](https://github.com/open-policy-agent/opa/issues/5766) - GitHub: [Source Code](https://github.com/open-policy-agent/regal/blob/main/bundle/regal/rules/testing/identically-named-tests/identically_named_tests.rego) diff --git a/docs/src/data/ecosystem/entries/alluxio.md b/docs/src/data/ecosystem/entries/alluxio.md index ae2c17a094..1bcd0f91f6 100644 --- a/docs/src/data/ecosystem/entries/alluxio.md +++ b/docs/src/data/ecosystem/entries/alluxio.md @@ -4,7 +4,7 @@ labels: category: authorization type: poweredbyopa tutorials: -- https://docs.alluxio.io/ee/user/2.10.0/en/security/OpenPolicyAgent-Integration.html +- https://documentation.alluxio.io/ee-ai-en/administration/security/enabling-authorization#management-api-authorization-with-open-policy-agent-opa inventors: - alluxio --- diff --git a/docs/src/data/ecosystem/entries/docker-machine.md b/docs/src/data/ecosystem/entries/docker-machine.md index 57e05ad369..42284a0d0a 100644 --- a/docs/src/data/ecosystem/entries/docker-machine.md +++ b/docs/src/data/ecosystem/entries/docker-machine.md @@ -8,7 +8,7 @@ labels: code: - https://github.com/open-policy-agent/opa-docker-authz tutorials: -- https://www.openpolicyagent.org/docs/latest/docker-authorization/ +- https://www.openpolicyagent.org/docs/docker-authorization inventors: - styra --- diff --git a/docs/src/data/ecosystem/entries/github-action-opa-rego-test.md b/docs/src/data/ecosystem/entries/github-action-opa-rego-test.md index 4e880f1eeb..15fc0e773f 100644 --- a/docs/src/data/ecosystem/entries/github-action-opa-rego-test.md +++ b/docs/src/data/ecosystem/entries/github-action-opa-rego-test.md @@ -18,4 +18,4 @@ docs_features: [GitHub Action for OPA Rego Policy Tests](docs/website/content/integrations/rego-test-assertions.md) by [Masterpoint](https://masterpoint.io/) is used to automate testing for your OPA (Open Policy Agent) Rego policies, generates a report with coverage information, and posts the test results as a comment on your pull requests, making it easy for your team to review and approve policies. -Use this to test your OPA Rego files for [Spacelift policies](https://docs.spacelift.io/concepts/policy), [Kubernetes Admission Controller policies](https://www.openpolicyagent.org/docs/kubernetes), [Docker authorization policies](https://www.openpolicyagent.org/docs/docker-authorization), or any other use case that uses [Open Policy Agent's policy language Rego](https://www.openpolicyagent.org/docs/latest/). This Action also updates PR comments with the test results in place to prevent duplication. +Use this to test your OPA Rego files for [Spacelift policies](https://docs.spacelift.io/concepts/policy), [Kubernetes Admission Controller policies](https://www.openpolicyagent.org/docs/kubernetes), [Docker authorization policies](https://www.openpolicyagent.org/docs/docker-authorization), or any other use case that uses [Open Policy Agent's policy language Rego](https://www.openpolicyagent.org/docs). This Action also updates PR comments with the test results in place to prevent duplication. diff --git a/docs/src/data/ecosystem/entries/kafka-authorization.md b/docs/src/data/ecosystem/entries/kafka-authorization.md index 30240311de..8104e07cec 100644 --- a/docs/src/data/ecosystem/entries/kafka-authorization.md +++ b/docs/src/data/ecosystem/entries/kafka-authorization.md @@ -11,7 +11,7 @@ blogs: tutorials: - https://www.openpolicyagent.org/docs/kafka-authorization code: -- https://github.com/StyraInc/opa-kafka-plugin +- https://github.com/StyraOSS/opa-kafka-plugin - https://github.com/llofberg/kafka-authorizer-opa - https://github.com/opencredo/opa-single-message-transformer inventors: @@ -34,7 +34,7 @@ docs_features: that uses OPA to make authorization decisions by calling the REST API. Installation and configuration instructions are available in the - project's [README](https://github.com/StyraInc/opa-kafka-plugin#installation). + project's [README](https://github.com/StyraOSS/opa-kafka-plugin#installation). --- Apache Kafka is a high-performance distributed streaming platform deployed by diff --git a/docs/src/data/ecosystem/entries/oidc.md b/docs/src/data/ecosystem/entries/oidc.md index d9509d37d1..a65d90b439 100644 --- a/docs/src/data/ecosystem/entries/oidc.md +++ b/docs/src/data/ecosystem/entries/oidc.md @@ -6,8 +6,8 @@ software: labels: category: security tutorials: -- https://www.openpolicyagent.org/docs/latest/oauth-oidc/ +- https://www.openpolicyagent.org/docs/oauth-oidc blogs: -- https://www.styra.com/blog/integrating-identity-oauth2-and-openid-connect-in-open-policy-agent +- https://www.styra.com/blog/integrating-identity-oauth2-and-openid-connect-in-open-policy-agent/ --- Integrating OpenID Connect (OIDC) with Open Policy Agent diff --git a/docs/src/data/ecosystem/entries/principled-evolution.md b/docs/src/data/ecosystem/entries/principled-evolution.md index ad91631621..6f778ca728 100644 --- a/docs/src/data/ecosystem/entries/principled-evolution.md +++ b/docs/src/data/ecosystem/entries/principled-evolution.md @@ -8,9 +8,6 @@ inventors: code: - https://github.com/principled-evolution/gopal - https://github.com/principled-evolution/aicertify -blogs: -- https://principledevolution.ai/blog/governance-policy-as-code-opa-trust-ai/ -# tutorials: # Optional: Add if specific tutorials exist --- Principled Evolution uses AICertify to generate the input context about AI systems and Gopal to provide the domain-specific Rego policies. OPA acts as the central decision engine, enabling automated, consistent, and auditable enforcement of AI governance rules via the standard Policy-as-Code approach familiar to the OPA community. This integration brings the power and flexibility of OPA to the critical domain of AI ethics and compliance. diff --git a/proposals/attic/REGO_V2_PROPOSAL.md b/proposals/attic/REGO_V2_PROPOSAL.md index 3d2227edbf..8f0b145052 100644 --- a/proposals/attic/REGO_V2_PROPOSAL.md +++ b/proposals/attic/REGO_V2_PROPOSAL.md @@ -44,7 +44,7 @@ composition. The signature of the rule declares the context to be provided upon evaluation, and the body is a collection of conditions and decisions. Please note that the definition of `expr` and `literal` are taken from -the [Common Expression Language](http://github.com/google/cel-spec) (CEL): +the [Common Expression Language](https://github.com/google/cel-spec) (CEL): ``` rule_decl diff --git a/wasm/README.md b/wasm/README.md index bc56709653..f143905211 100644 --- a/wasm/README.md +++ b/wasm/README.md @@ -12,7 +12,7 @@ This library does not make any backwards compatibility guarantees. ## Documentation -See the [OPA docs](https://www.openpolicyagent.org/docs/latest/wasm/) on Wasm for an overview of the integration, +See the [OPA docs](https://www.openpolicyagent.org/docs/wasm) on Wasm for an overview of the integration, compilation options, and more. ## Development