Create v5.0.0.md

README.md

@@ -91,6 +91,22 @@ If the service is not attached to any target group, this evaluation will be skip
 
 By default, `cage rollout` will only update the task definition of the service. If you want to update the service as well, you can specify `--updateService` flag. This flag will update the service with the service definition in the `service.json` file. This is useful when you want to update the service's network configuration, load balancer configuration, or other service-level configurations.
 
+### cage audit
+
+`audit` command scans container images used by an ECS service and summarizes ECR image scan findings. Basic usage is as follows:
+
+```bash
+$ cage audit --region ${AWS_REGION} ./deploy
+```
+
+You can also specify the target service directly:
+
+```bash
+$ cage audit --region ${AWS_REGION} --cluster ${ECS_CLUSTER} --service ${ECS_SERVICE}
+```
+
+By default, the output is a table with per-container status and severity counts. Use `--detail` to include vulnerability descriptions and `--json` to output the aggregated result as JSON.
+
 ### IAM Policy
 
 `cararycage` requires several IAM policies to run. Here is an example of IAM policy for `canarycage`:
@@ -117,6 +133,14 @@ By default, `cage rollout` will only update the task definition of the service.
       ],
       "Resource": "*"
     },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ecr:BatchGetImage",
+        "ecr:DescribeImageScanFindings"
+      ],
+      "Resource": "*"
+    },
     {
       "Effect": "Allow",
       "Action": [

changelogs/v5.0.0.md

@@ -0,0 +1,67 @@
+# canarycage v5.0.0 Release Notes
+
+## description
+
+Released at 2026/02/16 by [@keroxp](https://github.com/keroxp)
+
+This is the fifth major release since the first release in 2018.
+
+Canarycage v5 introduces a brand-new, powerful command `cage audit` that finds CVEs inside containers running in an ECS service.
+
+
+## cage audit command
+
+In short, `cage audit` is like `npm audit`. It does:
+
+- Scan a specified ECS service in a cluster.
+- Collect container image identifiers (tag, digest) described in Task Definition.
+- Query ECR for vulnerabilities.
+- Print the results in the CLI.
+
+It's simple, but ECS users haven't had an equivalent feature.
+
+### Usage
+
+```bash
+$ cage audit --region us-east-1 --cluster default --service my-service
+```
+
+where `./.deploy/service` is a directory containing `service.json` with `cluster` and `serviceName` fields defined.
+
+```bash
+$ cage audit --region us-east-1 ./.deploy/service
+```
+
+The `--json` option generates structured audit results.
+
+```bash
+$ cage audit --region us-east-1 --cluster default --service my-service --json
+```
+
+```bash
+$ cage audit --region us-east-1 --json ./.deploy/service
+```
+
+### Github Actions
+
+- https://github.com/loilo-inc/actions-audit-cage
+
+## misc changes
+
+- Version number format has been changed to include `v` (4.3.1 to v5.0.0).
+  - This aligns with Go module version rules.
+- `github.com/apex/log` is now retired.
+- `golang.org/x/xerrors` is now retired.
+- Added `--no-color` global option.
+
+## breaking changes
+### Newer version detection of upgrade command
+
+- Canarycage's version number format has changed to include `v` prefix.
+- Older cage binaries cannot detect newer releases with the `v` prefix.
+- Reinstall canarycage using: `go install github.com/loilo-inc/canarycage/cli/cage@v5.0.0`
+
+## project structure changes
+
+- Most CLI-related code is now placed inside `cli/cage/`
+