Add -ProjectTag to the AWS coverage script (#225)

Audits the project tag over the resource types the tag standard names,
classifying each as conforming, shared, nonconforming or missing and
validating values against the standard's list.

Separate from the managed-by sweep rather than a second dimension on it:
the two cover different resource types and a gap means different things.
A missing managed-by tag is a hygiene problem; a missing or wrong project
tag denies access, because the policies conditioning on it fail closed.

Author: ale210

scripts/README.md

@@ -43,6 +43,7 @@ This is a **tag sweep, not a Terraform state diff**. Read
 ./aws-terraform-coverage.ps1 -AwsProfile hfla-incubator   # pick a named profile
 ./aws-terraform-coverage.ps1 -CsvPath coverage.csv        # full classified list as CSV
 ./aws-terraform-coverage.ps1 -Region us-west-2            # narrow the sweep
+./aws-terraform-coverage.ps1 -ProjectTag                  # audit the project tag instead
 ```
 
 A full run makes several hundred read-only API calls and takes a few minutes.
@@ -103,6 +104,81 @@ under-reports.
   something stamped a provenance tag that is neither repo's and is not `exempt`.
   Worth investigating when it shows up.
 
+### Auditing the `project` tag instead (`-ProjectTag`)
+
+`-ProjectTag` runs a **different sweep against a different tag**, and answers a
+different question:
+
+| | Default run | `-ProjectTag` |
+|---|---|---|
+| Tag read | `managed-by` | `project` |
+| Scope | ~30 resource types, the whole account | the 8 resource types the tag standard names |
+| Question | does anything manage this? | which project owns this? |
+| A gap means | a hygiene problem | **an outage** |
+
+```powershell
+./aws-terraform-coverage.ps1 -ProjectTag             # summary and every nonconforming value
+./aws-terraform-coverage.ps1 -ProjectTag -ListArns   # plus every ARN missing the tag
+./aws-terraform-coverage.ps1 -ProjectTag -CsvPath project-tags.csv
+```
+
+The standard is
+[DR-Machine-to-machine-IAM-scoping](https://github.com/hackforla/devops/wiki/DR-Machine-to-machine-IAM-scoping)
+on the devops wiki. It defines the tag value as the Hack for LA **project** name
+— `vrms`, `home-unite-us`, `people-depot`, `civic-tech-jobs`, `civictechindex` —
+never an application, environment or repository name, plus `shared` for
+infrastructure belonging to no single project.
+
+**Why this matters more than the `managed-by` report.** The machine roles in
+[hackforla/incubator#206](https://github.com/hackforla/incubator/issues/206) are
+granted access on the basis of this tag matching, and **tag-based access control
+fails closed**. A resource whose tag is missing or wrong is not over-shared; it
+becomes unreachable. Run this and read it immediately before any policy change
+that conditions on the tag.
+
+Four outcomes per resource:
+
+- **`conforming`** — carries a value the standard recognises.
+- **`shared`** — carries `shared`, i.e. deliberately belongs to no one project.
+- **`nonconforming`** — carries a value that is *not* in the standard. **This is
+  the dangerous bucket, not `missing`.** Such a resource looks correctly tagged
+  in the console and still fails to match a policy, so it is always listed in
+  full rather than summarised.
+- **`missing`** — carries no `project` tag at all.
+
+Two things the report deliberately does *not* treat as equivalent:
+
+- **On the three machine IAM role families the tag is inventory only.** Policies
+  name the project literally, interpolated by Terraform, rather than
+  self-referencing `${aws:PrincipalTag/project}`, so a missing tag on a *role*
+  degrades reporting and cost allocation but breaks no access. A missing tag on
+  a *resource* does break access.
+- **A gap is not always fixable in a module.** Several untagged resources are
+  not in Terraform at all, so tagging them means a hand-applied change or
+  waiting on their import ticket. Check which before proposing where the fix
+  goes.
+
+The role families are matched by name, because nothing else distinguishes them.
+Note the naming is inverted: `incubator-prod-ecs-task-role` is the shared
+**execution** role, while the per-container **task** roles are the
+`ecs-container-*` ones.
+
+#### A trap worth knowing before you re-check a result by hand
+
+`aws ssm list-tags-for-resource` takes the parameter name as its resource id,
+leading slash included, and works fine. But **Git Bash rewrites any argument
+beginning with `/` into a Windows path**, so the identical command run there
+fails with `InvalidResourceId` — and a sweep that discards stderr reads that as
+an untagged parameter.
+
+That is exactly what produced the "0 of 37 SSM parameters carry a `project` tag"
+figure in
+[hackforla/incubator#197](https://github.com/hackforla/incubator/issues/197) and
+in the decision record. It was wrong: every parameter was tagged the whole time.
+This script is unaffected because it is PowerShell, but anyone spot-checking one
+of its results from Git Bash will hit it. Drop the leading slash there, or use
+PowerShell.
+
 ### Why it does not just use the Resource Groups Tagging API
 
 The obvious implementation is one `resourcegroupstaggingapi get-resources` call
@@ -199,3 +275,8 @@ created first. Open a follow-on issue if the report proves worth automating.
   added `managed-by = terraform-incubator`, for exactly this reporting purpose.
 - [hackforla/devops-security#172](https://github.com/hackforla/devops-security/issues/172) —
   the devops-security half of the same tagging work.
+- [hackforla/incubator#197](https://github.com/hackforla/incubator/issues/197) —
+  added `-ProjectTag`, and the audit it exists to make repeatable.
+- [hackforla/incubator#206](https://github.com/hackforla/incubator/issues/206) —
+  the epic whose policies condition on the `project` tag, and the reason a gap in
+  that tag is an outage rather than a reporting defect.