Merge pull request #44 from hakanson/syntaxhighlight

syntax highlighting support

Author: bisdavid

.gitignore

@@ -0,0 +1 @@
+docs/_site/

Best Practice Topics on hold/bp-all-about-the-data.md

@@ -13,10 +13,12 @@ In contrast, some types of applications, particularly web services, frequently d
 However, there are circumstances in which this API-centric approach is less than optimal. This is because the API operations are merely proxies for what customers truly want to protect: the underlying data and resources. If multiple API operations control access to the same resources, it can become difficult for administrators to reason about the many paths through which users can access the resources, and manage that access accordingly.
 
 To illustrate, consider a user directory holding the members of an organization. Users can be organized into groups, and one of the security goals is to prohibit discovery of group memberships by unauthorized parties. This service provides two API operations:
+
 + `listMembersOfGroup`
 + `listGroupMembershipsForUser`
 
 Both operations enable a user to discover group membership, so the permissions administrator must remember to coordinate access to both of them. Further compounding the difficulty, the service may later decide to release a new API to address more use cases, such as the following:
+
 + `isUserInGroups` – a new API to quickly test if a user belongs in one or more groups
 
 From a security perspective, this new API has opened a 3rd path to discover group memberships, thereby disrupting the carefully crafted permissions of the administrator.

Best Practice Topics on hold/bp-fine-grained-perms.md

@@ -11,7 +11,7 @@ One common regret in designing an application's authorization model is to start
 
 If fine-grained permissions are not defined upfront, it can require a complicated migration to convert the application code and policy statements to use a different, finer-grained set of permissions. For example, application code that previously authorized against a course-grained action will need to be modified to use the fine-grained actions. In addition, policies must be updated to reflect the migration, for example:
 
-```
+```cedar
 permit (
     principal == User::"6688f676-1aa9-456a-acf4-228340b54e9d",
     action in [Action::"listFolderContents", Action::"viewFile"],
@@ -25,7 +25,7 @@ To avoid this costly migration, it is beneficial to define fine-grained permissi
 
 As an example, the following schema snippet creates an action group that consists of multiple actions in a group called `security`.
 
-```
+```json
 "actions": {
     "unlock": {
         "memberOf": [ { "id": "security" } ]
@@ -39,12 +39,11 @@ As an example, the following schema snippet creates an action group that consist
 
 You can then reference that group of `security` actions as a single element in a policy by using syntax like the following.
 
-```
-permit(
+```cedar
+permit (
     principal,
     action in Action::"security",
     resource
-);    
+);
 
 ```
-</section>

Best Practice Topics on hold/bp-group-vs-attribute.md

@@ -13,7 +13,7 @@ Would this be best achieved by labeling each file with an attribute named `fileT
 
 Using an attribute supports policies like the following:
 
-```
+```cedar
 permit (
     principal == User::"5a250ea5-89bb-4b07-9a97-c8632e876124", // "alice"
     action == Action::"readFile",
@@ -26,7 +26,7 @@ when {
 
 Using a group supports policies like the following:
 
-```
+```cedar
 permit (
     principal == User::"5a250ea5-89bb-4b07-9a97-c8632e876124", // "alice"
     action == Action::"readFile",
@@ -38,7 +38,7 @@ In this example, it might not make a significant difference and the choice is do
 
 Attribute-based policies are helpful when the conditional expressions may be more complicated than simply checking equality. Imagine if the goal was to instead grant access to files under a certain size:
 
-```
+```cedar
 permit (
     principal == User::"5a250ea5-89bb-4b07-9a97-c8632e876124", // "alice"
     action == Action::"readFile",

Best Practice Topics on hold/bp-minimize-number-of-entities.md

@@ -11,8 +11,8 @@ nav_order: 4
 
 Entity types in Cedar are similar to concepts in other programming languages such as `class` or `struct`. They define the particular shape of something. For example, this guide has references sample types with names such as “User”, “File”, “Photo”, and so on.
 
-The addition of new entity types to an application increases the complexity of the application's authorization model. This means, for example, that a new entity type can imply new resource types and new actions. It can also mean new types of principals. From the perspective of customers, auditors, security engineers, and others with a desire to deeply understand and inspect the authorization properties of an application, the creation of entity types increases the surface area for inspection. This increase can be regarded as a significant change to an application’s risk model. Entity types should be introduced when this change is justified, such as when launching new features and capabilities. 
+The addition of new entity types to an application increases the complexity of the application's authorization model. This means, for example, that a new entity type can imply new resource types and new actions. It can also mean new types of principals. From the perspective of customers, auditors, security engineers, and others with a desire to deeply understand and inspect the authorization properties of an application, the creation of entity types increases the surface area for inspection. This increase can be regarded as a significant change to an application’s risk model. Entity types should be introduced when this change is justified, such as when launching new features and capabilities.
 
 Avoid a proliferation of entity types for other purposes. For example, Entity types should not be used as a resource-isolation mechanism by defining types such as `Account1`, `Account2`, and so on. Resource isolation can be achieved through other means, such as by using namespaces.
 
-A common practice when choosing the granularity of an entity type is to correlate one-to-one with the source authorities. This reflects the fact that entities are often pre-existing concepts in an application, already defined and managed by existing software. These existing concepts are typically evident in data models, API definitions, source code, and so on. The lowest friction path to bring these concepts into a Cedar authorization model is to represent them as they already exist in the applcation , perhaps with filtering and normalization on attributes to construct a clean basis for authorization.
+A common practice when choosing the granularity of an entity type is to correlate one-to-one with the source authorities. This reflects the fact that entities are often pre-existing concepts in an application, already defined and managed by existing software. These existing concepts are typically evident in data models, API definitions, source code, and so on. The lowest friction path to bring these concepts into a Cedar authorization model is to represent them as they already exist in the application , perhaps with filtering and normalization on attributes to construct a clean basis for authorization.

Best Practice Topics on hold/bp-permissions-in-attributes.md

@@ -10,23 +10,23 @@ nav_order: 4
 
 Attributes are best used as an *input* to the authorization decision. Don't use attributes to represent the permissions themselves, such as by declaring an attribute named “permittedFolders” on a User:
 
-```
-// ANTI-PATTERN: comingling permissions into user attributes
+```json
+// ANTI-PATTERN: commingling permissions into user attributes
 {
     "id": "df82e4ad-949e-44cb-8acf-2d1acda71798",
     "name": "alice",  
     "email": "[email protected]",
     "permittedFolders": [
-        "Folder::"c943927f-d803-4f40-9a53-7740272cb969",
-        "Folder::"661817a9-d478-4096-943d-4ef1e082d19a",
-        "Folder::"b8ee140c-fa09-46c3-992e-099438930894"
+        "Folder::\"c943927f-d803-4f40-9a53-7740272cb969\"",
+        "Folder::\"661817a9-d478-4096-943d-4ef1e082d19a\"",
+        "Folder::\"b8ee140c-fa09-46c3-992e-099438930894\""
     ]
 }
 ```
 
 And, subsequently using the attribute within a policy:
 
-```
+```cedar
 // ANTI-PATTERN
 permit (
     principal,
@@ -42,7 +42,7 @@ This approach transforms what would otherwise be a simple authorization model, w
 
 Another risk with this approach is the scaling factors when permissions are packed together inside a single `User` record. If the user has access to many things, the cumulative size of their `User` record will grow and perhaps approach the maximum limit of whatever system is storing the data.
 
-Instead, we recommend that you represent this scenario using multiple individual policies, perhaps usin policy templates to minimize repetition.
+Instead, we recommend that you represent this scenario using multiple individual policies, perhaps using policy templates to minimize repetition.
 
 ```//BETTER PATTERN
 permit (

Best Practice Topics on hold/bp-resource-lives-in-container.md

@@ -13,7 +13,7 @@ When designing an authorization model, you must associate every action with a pa
 
 This is an example of the generalized problem of resource creation. Resource creation is a bootstrapping problem, in that there must be a way for something to have permission to create resources even when no resources exist yet. The path to solving it is to recognize that every resource must exist within some container, and it is the container itself that acts as the anchor point for permissions. For example, if a folder pre-existed in the system, the ability to create a file can be modeled as a permission on that folder, since that is the location where permissions are necessary to instantiate the new resource.
 
-```
+```cedar
 permit (
   principal == User::"&ExampleGuid1;",
   action == Action::"createFile",
@@ -23,7 +23,7 @@ permit (
 
 However, what if no folder exists yet? Perhaps this is a new customer account in an application where no resources exist yet. In this situation, there is still a context that can be intuitively understood by asking: where can the customer create new files? Most likely, they shouldn’t be able to create files inside any random customer account. Rather, there is an implied context, and that context is the customer’s own account boundary. Therefore, the account represents the container for resource creation, and this can be explicitly modeled in a policy similar to the following example.
 
-```
+```cedar
 // Grants permission to create files within an account,
 // or within any sub-folder inside the account.
 permit (

Best Practice Topics on hold/bp-transitive-attributes.md

@@ -16,10 +16,9 @@ The decision between group-based or attribute-based access controls isn’t alwa
 
 ![\[Entities in a hierarchy automatically inherit the parent entity's attributes.\]](images/transitive-attributes.png)
 
-
 Because the attribute from the parent entity is inherited by the child entity, you can express policies like the following example.
 
-```
+```cedar
 permit (
   principal,
   action == Action::"readFile", 
@@ -32,7 +31,7 @@ when {
 };
 ```
 
-You might then ask the question "How are attribute values propagated across a hierarchy? Who does the propagation, when, and how?" The answer is that this is the role of the code that generates the who provides details about the entites to the authorization API. Recall that the entity information contains extra information about entities needed by the authorization evaluator. The extra information includes the parent-child relationships, the entity attributes, and whether to copy attribute values from a parent and inject them into child entities.
+You might then ask the question "How are attribute values propagated across a hierarchy? Who does the propagation, when, and how?" The answer is that this is the role of the code that generates the who provides details about the entities to the authorization API. Recall that the entity information contains extra information about entities needed by the authorization evaluator. The extra information includes the parent-child relationships, the entity attributes, and whether to copy attribute values from a parent and inject them into child entities.
 
 However, supporting transitive attributes can introduce complexity. One of the situations to watch for is conflicts across the inheritance space, such as nested folders, where one parent overrides the value inherited from its own parent. You have to choose whether to allow inheritance in a situation like this, and set rules that determine which attribute value is ultimately inherited by the child entity.
 

docs/.markdownlint.yaml

@@ -0,0 +1,8 @@
+# Default state for all rules
+default: true
+
+MD013: false
+
+MD022: false
+
+MD033: false

docs/Gemfile.lock

@@ -210,6 +210,8 @@ GEM
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     minitest (5.19.0)
+    nokogiri (1.15.3-x86_64-darwin)
+      racc (~> 1.4)
     nokogiri (1.15.3-x86_64-linux)
       racc (~> 1.4)
     octokit (4.25.1)
@@ -250,6 +252,7 @@ GEM
     webrick (1.8.1)
 
 PLATFORMS
+  x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES