@kensio/yulin 1.21.34 → 1.23.0

package/dist/service/wafv2/statement/sim-waf-rate-based-input.js

@@ -1,4 +1,3 @@
-import { simAwsProxiedSourceIp } from "../../../serve/http/sim-aws-proxied-connection.js";
 import { invalidSimWafRule } from "./sim-waf-rule-refusals.js";
 import { refuseUnsimulatedSimWafRateKeyType } from "./sim-waf-unsimulated-rate-based.js";
 /**
@@ -66,10 +65,11 @@ export function simWafRateWindowMilliseconds(statement, ruleName) {
 /**
  * Read how a rate-based statement groups the requests it counts.
  *
- * `IP` counts each client address on its own. Every request in this simulation
- * reports `simAwsProxiedSourceIp`, leaving one client for the whole
- * simulation. A rate limiting test sends its requests from one client and
- * expects the rule to trip, so that is the case anybody would write.
+ * `IP` counts each client address on its own. A request comes from
+ * `127.0.0.1` unless it states another address with `x-sim-aws-source-ip`, so
+ * a test that states none has one client for the whole simulation. That is
+ * the case a rate limiting test is usually written about: one client, sending
+ * until the rule trips.
  *
  * `CONSTANT` counts every request the statement sees together, and AWS asks
  * for a scope-down statement alongside it to say which requests those are. A
@@ -79,7 +79,7 @@ export function simWafRateAggregation(statement, ruleName) {
     const keyType = statement.AggregateKeyType;
     refuseUnsimulatedSimWafRateKeyType(keyType, ruleName);
     if (keyType === "IP") {
-        return () => simAwsProxiedSourceIp;
+        return (request) => request.sourceIp;
     }
     if (keyType === "CONSTANT") {
         if (statement.ScopeDownStatement === undefined) {

package/docs/services/cloudformation/README.md

@@ -2165,6 +2165,100 @@ console.log(stacks.size);
 See [simulated IAM](https://yulinsim.dev/services/iam/ "Simulated IAM usage docs") for the documents
 it takes.
 
+### The read calls an update makes
+
+CloudFormation calls a resource's read handler when it needs the resource's attributes and holds no
+fresh copy of them. A stack update that leaves a resource unchanged, while the new template reads one
+of its attributes through `Fn::GetAtt` or `Fn::Sub`, is one such case. The handler runs as the
+stack's execution role. Yulin authorizes each of its calls as the deployment's principal, after the
+update's own changes and before its outputs are resolved. A denied call fails the update, which is
+rolled back.
+
+The calls come from the resource type's entry in the CloudFormation registry. Yulin keeps the ones in
+the type's own service and authorizes them on the resource's ARN, built from the stack's account and
+Region and the resource's properties. A resource yulin skips is authorized the same way, since the
+snapshot and the properties are all this takes. A call IAM scopes to no resource type is
+authorized on `*`.
+
+```typescript sim-cloudformation-read-handler
+/**
+ * An update refused because the deploy Role may not read an unchanged
+ * resource whose attribute an output reads.
+ */
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  defaultAccountId: "123456789012",
+  defaultRegionName: "eu-west-2",
+});
+
+const deployer = await simAws.iam().makeDeployRole({
+  roleName: "cdk-exec",
+  policyDocument: {
+    Version: "2012-10-17",
+    Statement: {
+      Effect: "Allow",
+      Action: [
+        "s3:*",
+        "codeartifact:CreateDomain",
+        "codeartifact:CreateRepository",
+        "codeartifact:DescribeRepository",
+        "codeartifact:ListTagsForResource",
+      ],
+      Resource: "*",
+    },
+  },
+});
+
+const mirror = {
+  Domain: {
+    Type: "AWS::CodeArtifact::Domain",
+    Properties: { DomainName: "example" },
+  },
+  Repository: {
+    Type: "AWS::CodeArtifact::Repository",
+    Properties: { DomainName: "example", RepositoryName: "npm" },
+    DependsOn: "Domain",
+  },
+};
+const outputs = {
+  RepositoryArn: { Value: { "Fn::GetAtt": ["Repository", "Arn"] } },
+};
+
+const cloudFormation = simAws.cloudFormation();
+
+await cloudFormation.deployTemplate({
+  stackName: "artifacts",
+  template: { Resources: mirror, Outputs: outputs },
+  caller: deployer,
+});
+
+await cloudFormation.updateStack({
+  input: {
+    StackName: "artifacts",
+    TemplateBody: JSON.stringify({
+      Resources: { ...mirror, Sources: { Type: "AWS::S3::Bucket" } },
+      Outputs: outputs,
+    }),
+  },
+});
+
+try {
+  await cloudFormation.waitForStackUpdateComplete("artifacts");
+} catch (error) {
+  // "... is not authorized to perform:
+  // codeartifact:GetRepositoryPermissionsPolicy on resource:
+  // arn:aws:codeartifact:eu-west-2:123456789012:repository/example/npm"
+  console.log((error as Error).message);
+}
+```
+
+A resource the update creates or changes needs no read, because its own handler returned its
+attributes. A resource whose ARN cannot be built fails the update with the ARN variable it was
+missing. That happens to a resource yulin skips whose ARN holds an identifier its service would have
+generated, since only a created resource can give one.
+
 ### One caller for an assembly, and one per Stack
 
 `deployCdkOut(...)` takes a caller for every Stack in the assembly. A Stack deployed by a different
@@ -4579,4 +4673,16 @@ Each service's own docs describe what its resource types support.
   `InvokeRole` and `AddDefaultAuthorizerToCorsPreflight` fail the transform by name.
   `AutoPublishAlias` and `DeploymentPreference` are left out, because the simulator has one version
   of a function and nothing to shift traffic between.
+- A stack update authorizes the read handler calls of an unchanged resource whose attributes the
+  new template reads, and no other handler calls. The create, update and delete calls are the ones
+  each service makes itself. Creating a resource of a type yulin skips authorizes nothing. Of the read
+  calls, only those in the resource type's own service are authorized. The registry also lists calls
+  into other services (a KMS key, a role a property names), and a handler makes those only when a
+  property leads to them. See [the read calls an update makes](#the-read-calls-an-update-makes).
+- The read handler calls come from a snapshot of the registry and the Service Authorization
+  Reference, which `pnpm run cfn:read-handlers` refreshes. A resource type the snapshot leaves out is
+  not authorized at all. It leaves out a type whose read handler is unpublished, and one with no
+  resource type in the Service Authorization Reference named after it.
+- An `Fn::GetAtt` inside an `Fn::If` branch the conditions rule out still counts as reading the
+  resource.
 - Many advanced CloudFormation features are outside the simulation.

package/docs/services/iam/README.md

@@ -771,6 +771,12 @@ was created, exactly as `runAs` behaves. The header is stripped before the reque
 simulated service. A Lambda handler echoing `event.headers` sees none of the simulator's control
 metadata.
 
+`x-sim-aws-source-ip` is a control header of the same kind. It names the client address a request
+comes from (one IPv4 or IPv6 address), and a request naming none comes from `127.0.0.1`. A web ACL
+reads it (see
+[where a request comes from](https://yulinsim.dev/services/wafv2/#where-a-request-comes-from)). IAM
+policy evaluation does not read it.
+
 ```typescript sim-iam-served-request-caller
 /**
  * Naming the caller of an HTTP request into simulated AWS.

package/docs/services/wafv2/README.md

@@ -282,10 +282,11 @@ lets evaluation continue, the way it does for every other statement kind.
 window is measured against [simulated time](https://yulinsim.dev/time/), so `advanceBy` past it drops
 what the rule counted.
 
-`AggregateKeyType` is `IP` or `CONSTANT`. `IP` counts each client address on its own. Every request
-in this simulation reports `127.0.0.1`, leaving a web ACL with one client for the whole simulation.
-That is the case a rate limiting test is written about anyway (one client, sending until the rule
-trips), and it behaves here as it does on AWS. `CONSTANT` counts every request the statement sees
+`AggregateKeyType` is `IP` or `CONSTANT`. `IP` counts each client address on its own. A request
+comes from `127.0.0.1` unless it names another address (see
+[Where a request comes from](#where-a-request-comes-from)). A test that names none has one client for
+the whole simulation. That is the case a rate limiting test is usually written about (one client,
+sending until the rule trips). `CONSTANT` counts every request the statement sees
 together, and AWS requires a `ScopeDownStatement` alongside it to say which requests those are.
 
 A `ScopeDownStatement` narrows what the rule counts. Every statement kind in
@@ -463,17 +464,103 @@ are.
 
 ### Groups that read the caller
 
-The IP reputation, anonymous IP and Bot Control groups decide by who sent a request, and every
-request in this simulation comes from `127.0.0.1`. Each of their rules is declared-only. The group
-labels the request, takes the rule's documented action and honours overrides, as the groups that
-read the request do.
+The IP reputation, anonymous IP and Bot Control groups decide by who sent a request. AWS publishes
+their rule names, actions and labels, and none of the address lists or bot signatures behind them.
+Each of their rules is declared-only. The group labels the request, takes the rule's documented
+action and honours overrides, as the groups that read the request do.
 
 `AWSManagedRulesAmazonIpReputationList` holds `AWSManagedIPReputationList` and
 `AWSManagedReconnaissanceList`, which block, and `AWSManagedIPDDoSList`, which counts as AWS ships
 it. `AWSManagedRulesAnonymousIpList` holds `AnonymousIPList` (VPNs, proxies and Tor) and
 `HostingProviderIPList` (hosting and cloud providers other than AWS), which both block. A test
-declares a match by rule name, as above, and says which requests come from a flagged address that
-way.
+declares which addresses those five rules flag, and sends requests from them.
+
+#### Where a request comes from
+
+A request reaches this simulation in process or over loopback, and comes from `127.0.0.1`. The
+`x-sim-aws-source-ip` header names another client address (one IPv4 or IPv6 address). It works
+through `SimAwsHttp` and `serveSimAws` alike, and it is stripped before the request reaches the
+simulated service, as `x-sim-aws-caller` is. A value that is no address is refused with a 400 and
+`InvalidRequestCaller`. `evaluateRequest` takes the address as `sourceIp`.
+
+The address reaches the web ACL in front of a Cognito user pool or a REST API stage. The IP
+reputation and anonymous IP rules read it, and so does a rate limit aggregating on `IP`.
+
+`managedRules().onAddress` says which of those rules flag one address or a CIDR range. Only the
+rules of the IP reputation and anonymous IP groups can be declared by address, and a rule of any
+other group is refused. Declaring the same range again replaces it. An address inside two declared
+ranges is flagged by the rules of both, and a match declared for the request's path with
+`onRequest` applies beside them.
+
+```typescript sim-wafv2-anonymous-ip-list
+/**
+ * Blocking sign-ups from a Tor exit range with the anonymous IP list.
+ */
+
+import { CreateWebACLCommand } from "@aws-sdk/client-wafv2";
+
+import { SimAws } from "@kensio/yulin";
+
+const waf = new SimAws().wafV2();
+
+const visibility = {
+  SampledRequestsEnabled: false,
+  CloudWatchMetricsEnabled: false,
+  MetricName: "pool",
+};
+
+const created = await waf.createWebAcl(
+  new CreateWebACLCommand({
+    Name: "pool-acl",
+    Scope: "REGIONAL",
+    DefaultAction: { Allow: {} },
+    VisibilityConfig: visibility,
+    Rules: [
+      {
+        Name: "anonymous-ip",
+        Priority: 0,
+        OverrideAction: { None: {} },
+        Statement: {
+          ManagedRuleGroupStatement: {
+            VendorName: "AWS",
+            Name: "AWSManagedRulesAnonymousIpList",
+          },
+        },
+        VisibilityConfig: { ...visibility, MetricName: "anonymous-ip" },
+      },
+    ],
+  }),
+);
+
+waf.managedRules().onAddress("185.220.101.0/24", {
+  matches: ["AnonymousIPList"],
+});
+
+const signUp = (sourceIp: string): string =>
+  waf.evaluateRequest({
+    webAclArn: created.Summary!.ARN,
+    request: new Request("https://myapp-login.example.com/signup", {
+      headers: { "user-agent": "Mozilla/5.0" },
+    }),
+    sourceIp,
+  }).action;
+
+// "BLOCK"
+console.log(signUp("185.220.101.7"));
+
+// "ALLOW"
+console.log(signUp("203.0.113.9"));
+```
+
+A request over HTTP names its address in the header instead:
+
+```text
+POST /signup HTTP/1.1
+Host: myapp-login.auth.eu-west-2.amazoncognito.com
+x-sim-aws-source-ip: 185.220.101.7
+```
+
+The other kinds of statement that read the address are still held (see [Held input](#held-input)).
 
 Bot Control labels a request by the bot that sent it, and a verified bot is labelled and matches no
 rule. A test declares the bot.
@@ -865,6 +952,9 @@ and records no message.
 
 The pages are usually the point. `/signup`, `/confirm` and `/forgotPassword` are the ones that
 create an account or send an email, and a real web ACL on a user pool is usually written for them.
+A request to them can name the client it comes from in the `x-sim-aws-source-ip` header, for the
+anonymous IP list and the IP reputation list to decide on (see
+[Where a request comes from](#where-a-request-comes-from)).
 
 ```typescript sim-wafv2-cognito-user-pool
 /**
@@ -1537,9 +1627,10 @@ where AWS blocks every address outside the list and the simulation blocks none.
 
 A rule is held for any of these statement kinds:
 
-- `IPSetReferenceStatement`, `GeoMatchStatement` and `AsnMatchStatement`. Every request in this
-  simulation reports a source address of `127.0.0.1`, and a rule on where a request came from would
-  see one client for the whole simulation.
+- `IPSetReferenceStatement`, `GeoMatchStatement` and `AsnMatchStatement`. A request has a client
+  address (see [Where a request comes from](#where-a-request-comes-from)), and these statements are
+  not yet written to read it. A country or an ASN would also need an address database the simulation
+  does not have.
 - `SqliMatchStatement` and `XssMatchStatement`. AWS publishes no description of the detection they
   run.
 - `RuleGroupReferenceStatement`. A rule group of your own is a resource in its own right, and none
@@ -1551,7 +1642,7 @@ A rule is held for any of these statement kinds:
 
 A `RateBasedStatement` is evaluated (see [Rate limiting](#rate-limiting)). A rule using two of its
 aggregation key types is held. `FORWARDED_IP` and `ForwardedIPConfig` read the address from a
-forwarding header, which needs the source address variety an IP set is waiting on. `CUSTOM_KEYS` and
+forwarding header, and are held along with the IP set statement. `CUSTOM_KEYS` and
 `CustomKeys` aggregate on headers, cookies and query arguments, and are feasible and not part of
 this yet. `GetRateBasedStatementManagedKeys` is not simulated.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.34",
+  "version": "1.23.0",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
@@ -15,6 +15,7 @@
     "build": "pnpm clean && tsc -p tsconfig.build.json && pnpm oxlint:config && pnpm docs:index",
     "oxlint:config": "pnpm tsx scripts/mts/write-oxlint-config.mts",
     "docs:index": "pnpm tsx scripts/mts/write-llms-index.mts",
+    "cfn:read-handlers": "pnpm tsx scripts/mts/write-cfn-read-handlers.mts",
     "build:check": "tsc -p tsconfig.json --noEmit",
     "prepack": "pnpm build",
     "verify:pack": "pnpm tsx scripts/mts/verify-pack.mts",
@@ -290,16 +291,16 @@
     "conventional-changelog-conventionalcommits": "9.3.1",
     "esbuild": "^0.28.2",
     "eslint": "^10.8.0",
-    "eslint-plugin-jsdoc": "^64.0.1",
+    "eslint-plugin-jsdoc": "^65.0.0",
     "eslint-plugin-no-secrets": "^2.3.3",
     "eslint-plugin-security": "^4.0.1",
     "eslint-plugin-unicorn": "^76.0.0",
     "execa": "^10.0.0",
     "fta-cli": "^3.0.0",
     "hyparquet": "^1.29.2",
-    "hyparquet-writer": "^0.16.9",
+    "hyparquet-writer": "^0.18.0",
     "node-sql-parser": "^5.4.0",
-    "oxfmt": "^0.73.0",
+    "oxfmt": "^0.75.0",
     "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "25.0.9",