{"_id":"@aws-c2a/broadening-permissions","_rev":"2-54944f7ee7fc1f23575ae12a33c2e39f","name":"@aws-c2a/broadening-permissions","dist-tags":{"latest":"0.4.0"},"versions":{"0.4.0":{"name":"@aws-c2a/broadening-permissions","version":"0.4.0","description":"The broadening permissions preset for CDK Change Analyzer","main":"lib/index.js","scripts":{"build":"yarn clean && yarn compile","compile":"npx tsc --build","clean":"npx tsc --build --clean","clean:all":"git clean -fdx","lint":"eslint . --ext .ts","test":"npx jest"},"repository":{"type":"git","url":"git+https://github.com/cdklabs/awscdk-change-analyzer.git","directory":"packages/@aws-c2a/broadening-permissions"},"author":{"name":"Amazon Web Services","url":"https://aws.amazon.com"},"engines":{"node":">= 10.13.0 <13 || >=13.7.0"},"license":"Apache-2.0","dependencies":{"@aws-c2a/engine":"^0.4.0","@aws-c2a/models":"^0.4.0","@aws-c2a/rules":"^0.4.0","fifinet":"0.1.7"},"devDependencies":{"@aws-cdk/core":"^1.115.0","@babel/core":"^7.12.13","@babel/preset-env":"^7.12.13","@babel/preset-typescript":"^7.12.13","@types/jest":"^26.0.20","@types/node":"^14.14.33","@typescript-eslint/eslint-plugin":"^4.14.2","@typescript-eslint/parser":"^4.14.2","babel-jest":"^26.6.3","eslint":"^7.19.0","eslint-plugin-import":"^2.23.4","jest":"^26.5.0","ts-jest":"^26.5.0","ts-node":"^9.1.1","tsconfig-paths":"^3.9.0","typescript":"^4.1.3"},"publishConfig":{"access":"public"},"gitHead":"7a9a43b4f9dd00bcedeaa378b2022014337ee211","bugs":{"url":"https://github.com/cdklabs/awscdk-change-analyzer/issues"},"homepage":"https://github.com/cdklabs/awscdk-change-analyzer#readme","_id":"@aws-c2a/broadening-permissions@0.4.0","_nodeVersion":"10.19.0","_npmVersion":"lerna/4.0.0/node@v10.19.0+x64 (linux)","dist":{"integrity":"sha512-/SXDsCYOM0oiG/ys3CkCQkjnQYVkZT7BRqsZloPROzGOQ6b3b8H8Cu7eAcdU9OelVNBqm92GpylfY67QfpDnQg==","shasum":"eb177b1b2e535cf0e7f07175cc28ab032eb58932","tarball":"https://registry.npmjs.org/@aws-c2a/broadening-permissions/-/broadening-permissions-0.4.0.tgz","fileCount":44,"unpackedSize":200432,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJhMCjBCRA9TVsSAnZWagAAZOoP/0sa/ctK0ol4GZ2fCoFQ\nQ1p+e1n2MYfS7YhwUOHO0U5bpqRFn8h/KWYeUArwymZ3+J0XA87swwcjH5pw\n6kNe9GW+SstEZWwqHT88BgzvGCz8DfwxF5Sh68/qRQhRSf9Tc+EQ5B8Q3aLJ\nU/BbsnI5Xqlydoipgo3afnIhOYxy8uc+CPa2Yi9Igm6ocaGjrLfaMqc4VsEA\nChSesYh18WVVwrIPKoE8qG6Z0/98iw1ip0jD9V2AdTZNXNdzYCB8UaAUOjxh\nJsQdeEVBE12FXpwRtU/x3TvSYpmUwzBk5l7c2ALz+6vMcEwV2StNPNJy9jFV\nuAPFCfAEK1JQoMXsExqOWdwpp06uRHuGspkDTneq/pES2jVQjXp7+QGnPdUO\nKSUUpX+FR+yOUeMHyqwfT5ANdeHSSTdepjY8hNmU44VUdrNlENQUaOOcSWpD\nLwlKom+wUzIIvoXoGKOZWp1FVroM05gZE2rNyR4WHaIasNaLLbiazGqO2y/5\n3B5ocXWdL9s3elHwR3T+MnvW7WhbQSMd8O9x3F4CArfAcQ44vi0N6vIhW5U1\n+83GsRfUI3K6kTZPDD2+xjcebYe6woP1Qcy52QVS8uN58ViGvZ5Dy2423AL+\nydq8q24XV4HfAbuDUqyPNdUdm01zP7f1+S6wX6ZwNbAk6Vm+f0v+S4K8UiP9\nJ70k\r\n=Stzw\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDZuavWpx2o7iUMJL4zPmBEo0daoPZ0t+rdKy9TYW9PpgIhAKleBa2YMi3gyoX1D01HgOr/67QYDJsl/i3CJiH2ztjN"}]},"_npmUser":{"name":"aws-cdk-team","email":"aws-cdk-dev@amazon.com"},"directories":{},"maintainers":[{"name":"aws-cdk-team","email":"aws-cdk-dev@amazon.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/broadening-permissions_0.4.0_1630546113213_0.22652433513953363"},"_hasShrinkwrap":false}},"time":{"created":"2021-09-02T01:28:33.139Z","0.4.0":"2021-09-02T01:28:33.372Z","modified":"2023-11-21T16:29:34.813Z"},"maintainers":[{"email":"osa-3p@amazon.com","name":"amzn-oss"},{"email":"aws-cdk-dev@amazon.com","name":"aws-cdk-team"}],"description":"The broadening permissions preset for CDK Change Analyzer","homepage":"https://github.com/cdklabs/awscdk-change-analyzer#readme","repository":{"type":"git","url":"git+https://github.com/cdklabs/awscdk-change-analyzer.git","directory":"packages/@aws-c2a/broadening-permissions"},"author":{"name":"Amazon Web Services","url":"https://aws.amazon.com"},"bugs":{"url":"https://github.com/cdklabs/awscdk-change-analyzer/issues"},"license":"Apache-2.0","readme":"# AWS CDK Change Analyzer (C2A) - Engine\n\n`@aws-c2a/engine` is a package that the toolkit consumes to analyze two CloudFormation templates, extract\ntheir differences and produce a report of changes, customizable with a rules language. \n\n## Table of Contents\n1. [Platform Mapping](#Platform-Mapping)\n2. [Model Diffing](#Model-Diffing)\n3. [Aggregations](#Aggregations)\n4. [User Configuration](#User-Configuration)\n\n## Platform Mapping\n\nThe `platform-mapping` directory holds parsers that transform an artifact into an [InfraModel](../../README.md#InfraModel) - in this case, CloudFormation templates.\n\n### CloudFormation Parser\n\nThe CloudFormation parser takes any CloudFormation template and generates an [InfraModel](../../README.md#InfraModel)\n\nThe type of CloudFormation entity ([e.g. Resource, Parameter, Output](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html)) gets mapped to the type of _Component_. In the case of CloudFormation resources, in particular, their type gets mapped to the _Component_'s subtype (i.e. an AWS Lambda Function resource generates a _Component_ with type \"Resource\" and subtype \"AWS::Lambda::Function\").\n\nThe CloudFormation parser builds instances of **CFEntity**'s subclasses, which have the responsibility of properly building the respective _Components_, _Property Values_, and outgoing _Dependency Relationships_.\n\n![CFParser Component Diagram(1)](https://user-images.githubusercontent.com/26902818/124102721-85b2d900-da58-11eb-92ac-9f7c579e9861.png)\n\nThe **CFRef** class extracts references to entities in an entity's declaration, from the used intrinsic functions and resources' _DependsOn_ field.\n\nThe following image is an example of the created relationships:\n\n![CFN Parser](https://user-images.githubusercontent.com/26902818/124098679-aaa54d00-da54-11eb-959a-82266d746428.png)\n\n- References in intrinsic functions and in _DependsOn_ fields are transformed into Dependency Relationships\n- Structural Relationships connect resources to their stack\n\n### AWS CDK Parser\n\nParsing CDK-generated CloudFormation templates begins by using the [CloudFormation parser](#CloudFormation-Parser) and adding a _Component_ for each CDK Construct (extracted from the CloudFormation resources metadata). Afterwards, the stack _Component_ and its _Structural Relationships_ are removed and the CDK Construct Components are connected to the corresponding CloudFormation resource Components, as seen here:\n\n![CDK Parser](https://user-images.githubusercontent.com/26902818/124098672-aa0cb680-da54-11eb-9051-253934faaf34.png)\n\n## Model Diffing\n\nThe process of diffing InfraModels is contained in the `model-diffing` directory.\n\nIn the context of AWS CDK/CloudFormation, this is where we extract the operations (changes) that occurred between the old CloudFormation template and the new one.\n\nThe basic diff is created in `model-diffing/diff-creator.ts`. It groups components of the same type and subtype and matches them based on their name and similarity. This similarity is calculated by comparing the properties of each component, in `model-diffing/property-diff.ts`.\n\nSince detecting property operations and determining their similarity require the same underlying logic, they are both done simultaneously in `model-diffing/property-diff.ts`. A few notes on how this property diffing currently works:\n- When calculating similarity, there is currently no distinction between arrays and sets, so property array order is not considered. In other words, moving elements in an array as no effect on similarity. However, _Move_ operations are still created if an element at index 0 is matched with an element at index 1, for example.\n- A weight is associated with a given similarity value, which is the number of primitive values of the structure it applies to. Consider the following:\n    ```\n        {\n            a: {b: \"string\", c: \"string},\n            d: \"string\"\n        }\n    ```\n    Let's consider the string value of key \"d\" has been changed and the similarity between the new and old value is 0.5. However, the value of key \"a\" will have similarity 1 because it has not been changed. We can calculate the similarity of the full properties by doing a weighted average between both similarities. \"a\" will have a weight of 4 (because it holds 4 unchanged values with similarity 1, two keys and two values) and \"d\" will have a weight of 1 (because it has only 1 primitive value). The similarity for this example is 1*(4/5)+0.5*(1/5)=0.9.\n\n### Change Propagation\n\n`change-propagator.ts` is responsible for taking the observed changes and propagating them. This means:\n- Modified properties with _componentUpdateType_ of \"REPLACEMENT\" or \"POSSIBLE_REPLACEMENT\" generate an operation (change) of type _Replace_ for their component.\n- Renamed _Components_ have an new _Replace_ operation.\n- _Replace_ operations in _Components_ with incoming _Dependency Relationships_ generate an Update _Operation_ to the source property of such relationships, indicating that a referenced value may have changed.\n\n## Aggregations\n\nAggregations are structures that group Operations (changes) in a tree-like structure. based on their characteristics, according to a given structure. These are used to collapse changes when presenting them in an interface. Take the following example:\n\n![Aggregations Example](https://user-images.githubusercontent.com/26902818/124138218-54e59a80-da7e-11eb-8e8f-036af63da1f5.png)\n\nThese are resulting aggregations that narrow down operations by:\n- type and subtype of the affected Component\n- type of the operation\n- whether it affects a full component or just a property and, in case of the latter, the property path.\n\nThe characteristics that should be grouped at each level, and how, are described in `aggregations/component-operation/module-tree.ts`. Aggregation modules define how to split a group of operations and a module tree is a configuration of these modules that is used to generate the aggregations.\n\n## User Configuration\n\nUsers can write rules classify the risk of each change and if it should be automatically approved or rejected. These rules are based on a custom grammar in JSON syntax. Take the following example of a rule:\n\n```\n{\n    \"description\": \"Allow all insert operations\",\n    \"let\": {\n        \"insertChange\": { \"change\": {\"type\": \"INSERT\" } }\n    },\n    \"effect\": {\n        \"target\": \"insertChange\",\n        \"risk\": \"low\",\n        \"action\": \"approve\"\n    }\n}\n```\nThis is a very simple rule that sets automatic approval and low risk for all operations of type \"INSERT\". It is broken down below:\n- the \"let\" field associates objects with identifiers. In this case, there is only one identifier (\"insertChange\"). An identifier takes the value of all objects that match the query on the right. In this example, the query is matching all \"change\" objects of type \"INSERT\". So \"insertChange\" represents all insertions that occured.\n- the \"effect\" field applies consequences to a given change, identified as the \"target\". In this case, the \"target\" is \"insertChange\", which corresponds to all insert operations. The risk and automatic approval behavior for these changes are specified in the fields \"risk\" and \"action\" respectively.\n\nBelow is a more complex rule:\n\n```\n{\n    \"description\": \"CLOUDFRONT\",\n    \"let\": {\"cf\": { \"Resource\": \"AWS::CloudFront::Distribution\" } },\n    \"then\": [{\n            \"description\": \"Cloudfront Distributions origin changes are risky\",\n            \"let\": {\n                \"change\": { \"change\": {}, \"where\": \"change appliesTo cf.Properties.DistributionConfig.Origins\" }\n            },\n            \"effect\": {\n                \"risk\": \"high\"\n            }\n        }, {\n            \"description\": \"Cloudfront Distributions origin protocol security can increase\",\n            \"let\": {\n                \"change\": { \"change\": {}, \"where\": [\n                    \"change appliesTo cf.Properties.DistributionConfig.Origins.*.OriginProtocolPolicy\",\n                    \"change.old == 'http-only'\",\n                    \"change.new == 'https-only'\"\n                    ]\n                }\n            },\n            \"effect\": {\n                \"risk\": \"low\",\n                \"action\": \"approve\"\n            }\n    }]\n}\n```\nIn this rule, the \"then\" field is also used, which allows applying sub-rules that have access to the identifiers declared in their parent.\n\nComponent and Property objects allow accessing their inner properties by using the dot (\".\") notation. For example `component.someArray.*.property` will correspond to all values of key \"property\" in elements of array \"someArray\" inside \"component\".\n\nYou can also notice that queries can have a \"when\" field, specifying further conditions, such as: checking if a change applies to a given object (Component or Property) with the operator \"applies to\"; comparing old and new values of changes to properties with the \".old\" accessor and \"==\" operator.\n\nThis rules language maps finds the objects in the graph generated from the [InfraModelDiff](../../README.md#InfraModelDiff) and traverses its edges when relating objects, such as when navigating properties or checking whether a change applies to an object.\n","readmeFilename":"README.md"}