@hoanghainh/komagu 2.1.1 → 2.2.0

package/operate/tests/test_ai_verdicts.py

@@ -0,0 +1,200 @@
+"""Issue #323: replies with stray quotes in code fields parse, and flagged verdicts without a finding
+become low-confidence anchored findings (offline replay of Evaluation Run 5, run A)."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+from operate.ai.anchoring import AnchorReport, anchor_findings, load_anchors
+from operate.ai.client import LLMClient, repair_json_quotes
+from operate.ai.runner import HeadlessAIRunner
+from operate.ai.verdicts import verdict_findings
+from operate.tests.test_ai_anchoring import _ScriptedClient
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+EVAL_RUN_5 = REPO_ROOT / "assess" / "lsa" / "examples" / "eval-run-5"
+SCORER = REPO_ROOT / "assess" / "lsa" / "tests" / "score_findings.py"
+
+# The slip that cost batch routes-001 in Run 4 and Run 5, run B (raw reply was not archived)
+SLIPPED_REPLY = """Here is the audit:
+```json
+{
+  "batch_id": "routes-001",
+  "findings": [
+    {
+      "finding_id": "BOLA-R-0001",
+      "category": "bola",
+      "subtype": "missing_ownership_check",
+      "title": "BOLA in GET /orders/{id}",
+      "route_id": "R-0001",
+      "location": {"file": "app/orders.php", "start_line": 3},
+      "evidence": [{"file": "app/orders.php", "start_line": 3, "code": "$id = $_GET["id"];", "why": "id from request"}],
+      "severity": "high",
+      "confidence": "high",
+      "cwe": ["CWE-639"],
+      "recommendation": {"summary": "Bind to the session user", "code_before": "SELECT * FROM orders WHERE id = " + id", "code_after": "... AND user_id = ?"},
+      "status": "unverified"
+    }
+  ],
+  "route_verdicts": [{"route_id": "R-0001", "verdict": "vulnerable"}]
+}
+```"""
+
+
+class TestRepairJsonQuotes(unittest.TestCase):
+    def test_run_5_slip_parses_after_repair(self) -> None:
+        with self.assertRaises((RuntimeError, ValueError)):
+            LLMClient.extract_json(SLIPPED_REPLY)
+        parsed = json.loads(repair_json_quotes(SLIPPED_REPLY))
+        rec = parsed["findings"][0]["recommendation"]
+        self.assertEqual(rec["code_before"], 'SELECT * FROM orders WHERE id = " + id')
+        self.assertEqual(parsed["findings"][0]["evidence"][0]["code"], '$id = $_GET["id"];')
+        self.assertEqual(parsed["route_verdicts"], [{"route_id": "R-0001", "verdict": "vulnerable"}])
+
+    def test_valid_json_is_unchanged(self) -> None:
+        doc = {"a": 'say "hi"', "b": ["x", {"c": "back\\slash"}], "d": 1}
+        text = json.dumps(doc, indent=2)
+        self.assertEqual(repair_json_quotes(text), text)
+        self.assertEqual(json.loads(repair_json_quotes("Answer: " + json.dumps(doc) + " done")), doc)
+
+
+class TestRunnerParsesRepairedReply(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="komagu_repair_"))
+        self.target, self.out = self.tmp / "app", self.tmp / "out"
+        (self.target / "app").mkdir(parents=True)
+        (self.target / "app" / "orders.php").write_text("<?php\nsession_start();\n$id = $_GET['id'];\n", encoding="utf-8")
+        (self.out / "routes").mkdir(parents=True)
+        route = {"route_id": "R-0001", "method": ["GET"], "path": "/orders/{id}",
+                 "handler": {"file": "app/orders.php", "line": 3}, "needs_bola_audit": True}
+        (self.out / "routes" / "routes-001.json").write_text(json.dumps({"routes": [route]}), encoding="utf-8")
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_slipped_bola_reply_keeps_its_findings_without_retry(self) -> None:
+        runner = HeadlessAIRunner(self.target, self.out, _ScriptedClient([SLIPPED_REPLY]))
+        runner.audit_bola_routes()
+        doc = json.loads((self.out / "findings" / "bola-routes-001.json").read_text(encoding="utf-8"))
+        self.assertEqual([f["finding_id"] for f in doc["findings"]], ["BOLA-R-0001"])
+        self.assertEqual(doc["findings"][0]["recommendation"], "Bind to the session user")
+        self.assertEqual((runner.retries, runner.parse_failures), ({}, {}))
+        self.assertEqual(runner.repaired, {"4a-bola-auditor": ["routes-001"]})
+        self.assertTrue((self.out / "ai-raw" / "4a-bola-auditor-routes-001.txt").is_file())
+        stats = json.loads(runner.write_run_stats().read_text(encoding="utf-8"))
+        self.assertEqual(stats["repaired"], {"4a-bola-auditor": ["routes-001"]})
+
+    def test_vulnerable_verdict_without_finding_becomes_a_finding(self) -> None:
+        reply = json.dumps({"batch_id": "routes-001", "findings": [],
+                            "route_verdicts": [{"route_id": "R-0001", "verdict": "vulnerable"}]})
+        runner = HeadlessAIRunner(self.target, self.out, _ScriptedClient([reply]))
+        runner.audit_bola_routes()
+        doc = json.loads((self.out / "findings" / "bola-routes-001.json").read_text(encoding="utf-8"))
+        (f,) = doc["findings"]
+        self.assertEqual((f["category"], f["subtype"], f["confidence"], f["status"]),
+                         ("bola", "missing_ownership_check", "low", "unverified"))
+        self.assertEqual(f["location"], {"file": "app/orders.php", "start_line": 3})
+        self.assertEqual(f["endpoint"], {"method": "GET", "path": "/orders/{id}"})
+        self.assertEqual(runner.findings_from_verdicts, {"4a-bola-auditor": [f["finding_id"]]})
+
+    def test_the_4a_template_no_longer_asks_for_code_fields(self) -> None:
+        client = _ScriptedClient(['{"findings": [], "route_verdicts": []}'])
+        HeadlessAIRunner(self.target, self.out, client).audit_bola_routes()
+        prompt = client.calls[0][-1]["content"]
+        self.assertNotIn("code_before", prompt)
+        self.assertNotIn("code_after", prompt)
+
+
+class TestVerdictFindings(unittest.TestCase):
+    RECORDS = {
+        "M-1": {"candidate_id": "M-1", "file": "a.php", "line": 6, "subtype": "privileged_field_writable"},
+        "I-1": {"candidate_id": "I-1", "file": "q.js", "line": 9, "category_hint": "nosql_injection",
+                "subtype_hint": "operator_injection|dynamic_identifier"},
+    }
+
+    def test_only_flagged_uncovered_known_ids(self) -> None:
+        verdicts = [{"candidate_id": "M-1", "verdict": "needs_review"}, {"candidate_id": "I-1", "verdict": "safe"},
+                    {"candidate_id": "M-9", "verdict": "vulnerable"}, "noise"]
+        (f,) = verdict_findings(verdicts, [], "candidate_id", self.RECORDS, "mass_assignment")
+        self.assertEqual((f["finding_id"], f["subtype"], f["cwe"]), ("MASS-M-1-verdict", "privileged_field_writable", ["CWE-915"]))
+        self.assertIn("needs_review", f["impact"])
+        covered = [{"candidate_id": "M-1"}]
+        self.assertEqual(verdict_findings(verdicts, covered, "candidate_id", self.RECORDS, "mass_assignment"), [])
+
+    def test_finding_linked_by_finding_ids_or_finding_id_covers_the_verdict(self) -> None:
+        findings = [{"finding_id": "MASS-M-1-1"}]
+        self.assertEqual(verdict_findings([{"candidate_id": "M-1", "verdict": "vulnerable"}], findings,
+                                          "candidate_id", self.RECORDS, "mass_assignment"), [])
+        listed = [{"candidate_id": "M-1", "verdict": "vulnerable", "finding_ids": ["F-9"]}]
+        self.assertEqual(verdict_findings(listed, [{"finding_id": "F-9"}], "candidate_id", self.RECORDS, "mass_assignment"), [])
+        # M-1 must not be covered by a finding for M-10
+        (f,) = verdict_findings([{"candidate_id": "M-1", "verdict": "vulnerable"}], [{"finding_id": "MASS-M-10-1"}],
+                                "candidate_id", self.RECORDS, "mass_assignment")
+        self.assertEqual(f["candidate_id"], "M-1")
+
+    def test_category_and_subtype_hints_from_the_record(self) -> None:
+        (f,) = verdict_findings([{"candidate_id": "I-1", "verdict": "vulnerable"}], [], "candidate_id",
+                                self.RECORDS, "sql_injection")
+        self.assertEqual((f["category"], f["subtype"], f["cwe"]), ("nosql_injection", "operator_injection", ["CWE-943"]))
+
+    def test_generated_findings_match_the_finding_schema(self) -> None:
+        sys.path.insert(0, str(REPO_ROOT / "assess" / "lsa" / "scripts"))
+        from merge_findings import load_validator
+        validate = load_validator("finding.schema.json")
+        records = {**self.RECORDS, "R-1": {"route_id": "R-1", "method": ["POST"], "path": "/users/{id}/role",
+                                           "handler": {"file": "admin.php", "line": 4}}}
+        for key, record_id, category in (("route_id", "R-1", "bola"), ("route_id", "R-1", "bfla"),
+                                         ("candidate_id", "M-1", "mass_assignment"), ("candidate_id", "I-1", "sql_injection")):
+            with self.subTest(category=category):
+                (f,) = verdict_findings([{key: record_id, "verdict": "vulnerable"}], [], key, records, category)
+                self.assertEqual(validate(f), [])
+
+
+class TestReplayRun5RunA(unittest.TestCase):
+    """The four flagged mass assignment candidates of run A become located findings; no SAFE marker is hit."""
+
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="komagu_replay_"))
+        self.out = self.tmp / "gptoss-a"
+        shutil.copytree(EVAL_RUN_5 / "gptoss-a", self.out)
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def score(self) -> dict:
+        proc = subprocess.run([sys.executable, str(SCORER), "--verdicts", str(EVAL_RUN_5 / "ground-truth.json"), str(self.out)],
+                              capture_output=True, text=True, check=True)
+        return json.loads(proc.stdout)
+
+    def test_replay_recovers_the_four_mass_assignment_items(self) -> None:
+        cands = json.loads((self.out / "mass-assignment.candidates.json").read_text(encoding="utf-8"))["candidates"]
+        records = {c["candidate_id"]: c for c in cands}
+        # the fixtures are not in the archive; anchoring only needs the Tier 1 records
+        anchors, report = load_anchors(self.out, self.tmp), AnchorReport()
+        generated = []
+        for path in sorted((self.out / "findings").glob("priv-*.json")):
+            doc = json.loads(path.read_text(encoding="utf-8"))
+            extra = verdict_findings(doc["candidate_verdicts"], doc["findings"], "candidate_id", records, "mass_assignment")
+            generated += anchor_findings(extra, anchors, self.tmp, report)
+            generated += verdict_findings(doc["privilege_route_verdicts"], doc["findings"], "route_id", {}, "bfla")
+        self.assertEqual(sorted(f["candidate_id"] for f in generated), ["M-0001", "M-0002", "M-0011", "M-0012"])
+        self.assertEqual(report.unanchored, [])
+
+        merged = json.loads((self.out / "findings.json").read_text(encoding="utf-8"))
+        merged["findings"] += generated
+        (self.out / "findings.json").write_text(json.dumps(merged), encoding="utf-8")
+        mass = self.score()["per_category"]["mass_assignment"]
+        # before: 10 / 15; register.php:4 stays missed (rejected by the verifier, fixture under review)
+        self.assertEqual((mass["found"], mass["missed"]), (14, ["php-plain/register.php:4"]))
+        for cat, row in self.score()["per_category"].items():
+            self.assertEqual(row["false_positive_on_safe_code"], [], cat)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoanghainh/komagu",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Security-First Legacy Modernization Platform CLI (LSA Kit, IAM Perimeter, Cross-User Testing)",
   "main": "remediate/authz/nodejs/src/index.js",
   "types": "remediate/authz/nodejs/src/index.d.ts",

package/remediate/authz/README.md

@@ -276,7 +276,128 @@ func RegisterOrderRoutes(mux *http.ServeMux, authorizer *authz.Authorizer) {
 
 ---
 
-## 7. Test Verification & D5 Runner
+## 7. Function-Level Authorization (BFLA) and Mass Assignment
+
+These helpers fix the two privilege findings of the audit kit: **BFLA** (CWE-285, see
+[`bfla-patterns.md`](../../assess/lsa/knowledge/bfla-patterns.md)) and **mass assignment** (CWE-915, see
+[`mass-assignment-patterns.md`](../../assess/lsa/knowledge/mass-assignment-patterns.md)).
+
+The role guard behaves the same in every module:
+
+| Rule | Behaviour |
+|---|---|
+| Role source | The authenticated principal only (claims, granted authorities, `req.user`, request context). Never route values, query, form, body or headers |
+| Not authenticated | 401 |
+| Match | The caller needs at least one of the listed roles (exact, case-sensitive) |
+| Denied | 403 by default; a module setting answers 404 to hide the endpoint |
+| Audit | Each denial emits `Komagu.Authorization.RoleDenied` with actor ids and the required roles |
+| Bad configuration | Empty or blank role lists and unsupported deny statuses fail fast |
+
+For mass assignment, bind a DTO that lists only the fields the caller may change and copy them onto the
+entity explicitly. Never bind the entity itself or rely on `[Bind(Include = "...")]`. Where the input is a
+map, `allowFields` keeps only the listed keys and never mutates its input.
+
+### .NET 8
+
+```csharp
+// Program.cs
+builder.Services.AddKomaguAuthorization();
+builder.Services.ConfigureKomaguRoles(o =>
+{
+    o.RoleClaimType = "role";               // default: ClaimTypes.Role
+    o.DenyWith = RoleDenyResponse.NotFound; // default: Forbidden (403)
+});
+
+[HttpDelete("admin/users/{id}")]
+[RequireRole("admin", "support")]           // any one role; several attributes must all pass
+public IActionResult DeleteUser(int id) => NoContent();
+
+public sealed record ProfileUpdateDto(string Name, string Email)
+{
+    public void ApplyTo(Customer customer)
+    {
+        customer.Name = Name;
+        customer.Email = Email;             // Role / IsAdmin / Balance cannot be set from the request
+    }
+}
+```
+
+`[RequireRole]` is an authorization filter, so it runs before model binding.
+
+### Spring Boot 3
+
+```kotlin
+@RestController
+@RequestMapping("/admin")
+@RequireRole("admin")                                       // class-level default
+class AdminController(private val users: UserService) {
+    @DeleteMapping("/users/{id}")
+    fun delete(@PathVariable id: String) = users.delete(id) // ROLE_admin or admin passes
+
+    @GetMapping("/audit")
+    @RequireRole("admin", "auditor", hideAsNotFound = true) // method-level overrides class-level
+    fun audit() = users.auditTrail()
+}
+
+data class ProfileUpdate(val name: String, val email: String) {
+    fun applyTo(account: UserAccount) = account.copy(name = name, email = email)
+}
+val safe = allowFields(body, "name", "email")               // io.komagu.security.data
+```
+
+Roles are the granted authorities of the authentication in `SecurityContextHolder`; one leading `ROLE_` is
+ignored on both sides. Map JWT scopes or role claims to authorities in your `JwtAuthenticationConverter`.
+Set `komagu.security.role.hide-denied-as-not-found=true` to answer every denial with 404. Spring Boot's
+default `ObjectMapper` silently drops unknown fields such as `role`; the explicit copy is what keeps them out.
+
+### Node.js (Express & NestJS)
+
+```js
+const { requireRole, allowFields } = require('@hoanghainh/komagu-authz');
+
+app.delete('/admin/users/:id', requireRole('admin'), deleteUser);
+app.post('/ops/rotate-keys', requireRole(['ops', 'admin'], { denyStatus: 404 }), rotateKeys);
+
+app.patch('/me', async (req, res) => {
+  const changes = allowFields(req.body, ['name', 'email']); // role / isAdmin are dropped
+  res.json(await users.update(req.user.userId, changes));
+});
+```
+
+```ts
+@Controller('admin')
+@UseGuards(KomaguRoleGuard)
+export class AdminController {
+  @Delete('users/:id')
+  @RequireRole('admin')
+  deleteUser(@Param('id') id: string) { /* ... */ }
+}
+```
+
+Roles come from `req.user.roles` and `req.user.role`. `allowFields` ignores `__proto__`, `constructor` and
+`prototype`, and copies values by reference.
+
+### Go
+
+```go
+// After verifying the token, attach the identity in your authentication middleware.
+ctx := authz.WithIdentity(r.Context(), authz.Identity{UserID: claims.Sub, TenantID: claims.TenantID, Roles: claims.Roles})
+
+auth := authz.NewAuthorizer(nil)
+mux.Handle("/admin/users", authenticate(auth.RequireRole([]string{"admin"})(adminUsers)))
+mux.Handle("/internal/reindex", authenticate(auth.RequireRole(
+    []string{"admin", "ops"}, authz.WithDenyStatus(http.StatusNotFound))(reindex)))
+
+patch := authz.AllowFields(body, "name", "email")           // or decode into a narrow struct:
+dec := json.NewDecoder(r.Body)
+dec.DisallowUnknownFields()                                 // {"role":"admin"} -> 400
+```
+
+`RequireRole` panics at route registration on an empty role list or a deny status other than 403 / 404.
+
+---
+
+## 8. Test Verification & D5 Runner
 
 All multi-language adapters verify identical BOLA defense invariants:
 

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/KomaguRoleOptions.cs

@@ -0,0 +1,20 @@
+namespace Komagu.Security.AspNetCore;
+
+using System.Security.Claims;
+
+/// <summary>
+/// Options for <see cref="RequireRoleAttribute"/> / <see cref="RoleAuthorizationFilter"/>.
+/// </summary>
+public sealed class KomaguRoleOptions
+{
+    /// <summary>
+    /// Claim type read from the authenticated <see cref="ClaimsPrincipal"/> to obtain the caller's roles.
+    /// Defaults to <see cref="ClaimTypes.Role"/>; set to <c>"role"</c> or <c>"roles"</c> for raw JWT claims.
+    /// </summary>
+    public string RoleClaimType { get; set; } = ClaimTypes.Role;
+
+    /// <summary>
+    /// Response returned when an authenticated caller lacks every required role. Defaults to 403 Forbidden.
+    /// </summary>
+    public RoleDenyResponse DenyWith { get; set; } = RoleDenyResponse.Forbidden;
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/RequireRoleAttribute.cs

@@ -0,0 +1,34 @@
+namespace Komagu.Security.AspNetCore;
+
+using Microsoft.AspNetCore.Mvc;
+
+/// <summary>
+/// Declarative function-level authorization (BFLA defense): the authenticated caller must hold at least one of the
+/// given roles. Roles are read only from verified <c>HttpContext.User</c> claims, never from the request.
+/// Returns 401 when unauthenticated and 403 (or 404, see <see cref="KomaguRoleOptions.DenyWith"/>) when denied.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
+public sealed class RequireRoleAttribute : TypeFilterAttribute
+{
+    public RequireRoleAttribute(params string[] roles)
+        : base(typeof(RoleAuthorizationFilter))
+    {
+        if (roles == null || roles.Length == 0)
+        {
+            throw new ArgumentException("At least one required role must be specified.", nameof(roles));
+        }
+
+        if (roles.Any(string.IsNullOrWhiteSpace))
+        {
+            throw new ArgumentException("Required roles must not be null, empty or whitespace.", nameof(roles));
+        }
+
+        Roles = roles.ToArray();
+        Arguments = new object[] { Roles.ToArray() };
+    }
+
+    /// <summary>
+    /// Roles accepted by this guard; holding any one of them (exact, ordinal match) grants access.
+    /// </summary>
+    public IReadOnlyList<string> Roles { get; }
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/RoleAuthorizationFilter.cs

@@ -0,0 +1,114 @@
+namespace Komagu.Security.AspNetCore;
+
+using System.Diagnostics;
+using Komagu.Security.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+using Microsoft.Extensions.Options;
+
+/// <summary>
+/// Authorization filter enforcing that the authenticated caller holds at least one required role.
+/// Runs before model binding, so request-supplied values (route, query, form, body, headers) can never grant a role.
+/// </summary>
+public sealed class RoleAuthorizationFilter : IAsyncAuthorizationFilter
+{
+    /// <summary>
+    /// Audit event name emitted on a role denial.
+    /// </summary>
+    public const string RoleDeniedEventName = "Komagu.Authorization.RoleDenied";
+
+    private readonly string[] _requiredRoles;
+    private readonly ISecurityAuditSink _auditSink;
+    private readonly IKomaguAuthorizationService _authorizationService;
+    private readonly KomaguRoleOptions _options;
+
+    public RoleAuthorizationFilter(
+        string[] requiredRoles,
+        ISecurityAuditSink auditSink,
+        IKomaguAuthorizationService authorizationService,
+        IOptions<KomaguRoleOptions> options)
+    {
+        ArgumentNullException.ThrowIfNull(requiredRoles);
+        if (requiredRoles.Length == 0 || requiredRoles.Any(string.IsNullOrWhiteSpace))
+        {
+            throw new ArgumentException("At least one non-empty required role must be specified.", nameof(requiredRoles));
+        }
+
+        _requiredRoles = requiredRoles.ToArray();
+        _auditSink = auditSink ?? throw new ArgumentNullException(nameof(auditSink));
+        _authorizationService = authorizationService ?? throw new ArgumentNullException(nameof(authorizationService));
+        _options = options?.Value ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    public async Task OnAuthorizationAsync(AuthorizationFilterContext context)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        var user = context.HttpContext.User;
+
+        // Invariant: Unauthenticated callers get 401 before any role evaluation
+        if (user?.Identity?.IsAuthenticated != true)
+        {
+            context.Result = new UnauthorizedResult();
+            return;
+        }
+
+        // Roles come only from the verified principal; exact, ordinal match against any required role
+        var roleClaimType = string.IsNullOrWhiteSpace(_options.RoleClaimType)
+            ? System.Security.Claims.ClaimTypes.Role
+            : _options.RoleClaimType;
+
+        var hasRole = user.FindAll(roleClaimType)
+            .Any(c => _requiredRoles.Contains(c.Value, StringComparer.Ordinal));
+
+        if (hasRole)
+        {
+            return;
+        }
+
+        context.Result = _options.DenyWith == RoleDenyResponse.NotFound
+            ? new NotFoundResult()
+            : new StatusCodeResult(StatusCodes.Status403Forbidden);
+
+        await EmitDenialAsync(context).ConfigureAwait(false);
+    }
+
+    private async ValueTask EmitDenialAsync(AuthorizationFilterContext context)
+    {
+        var httpContext = context.HttpContext;
+        try
+        {
+            var auditEvent = new SecurityAuditEvent
+            {
+                Timestamp = DateTimeOffset.UtcNow,
+                EventName = RoleDeniedEventName,
+                TraceId = Activity.Current?.Id ?? httpContext.TraceIdentifier,
+                ActorUserId = TryRead(() => _authorizationService.GetCurrentUserId(httpContext.User)),
+                ActorTenantId = TryRead(() => _authorizationService.GetCurrentTenantId(httpContext.User)),
+                ResourceType = "Endpoint",
+                ResourceId = context.ActionDescriptor?.DisplayName ?? httpContext.Request.Path.Value,
+                ClientIp = httpContext.Connection.RemoteIpAddress?.ToString(),
+                Reason = $"Missing required role: caller holds none of [{string.Join(", ", _requiredRoles)}]"
+            };
+
+            await _auditSink.EmitAsync(auditEvent, httpContext.RequestAborted).ConfigureAwait(false);
+        }
+        catch
+        {
+            // Auditing failures must not mask or alter the denial outcome
+        }
+    }
+
+    private static string? TryRead(Func<string> read)
+    {
+        try
+        {
+            return read();
+        }
+        catch (UnauthorizedAccessException)
+        {
+            return null;
+        }
+    }
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/RoleDenyResponse.cs

@@ -0,0 +1,17 @@
+namespace Komagu.Security.AspNetCore;
+
+/// <summary>
+/// HTTP response returned by <see cref="RoleAuthorizationFilter"/> when an authenticated caller lacks every required role.
+/// </summary>
+public enum RoleDenyResponse
+{
+    /// <summary>
+    /// HTTP 403 Forbidden (default).
+    /// </summary>
+    Forbidden,
+
+    /// <summary>
+    /// HTTP 404 Not Found, hiding the existence of the privileged endpoint.
+    /// </summary>
+    NotFound
+}

package/remediate/authz/dotnet/src/Komagu.Security.AspNetCore/ServiceCollectionExtensions.cs

@@ -16,6 +16,7 @@ public static class ServiceCollectionExtensions
     {
         services.TryAddSingleton<ISecurityAuditSink, LoggingSecurityAuditSink>();
         services.TryAddScoped<IKomaguAuthorizationService, DefaultKomaguAuthorizationService>();
+        services.AddOptions<KomaguRoleOptions>();
         return services;
     }
 
@@ -27,6 +28,21 @@ public static class ServiceCollectionExtensions
     {
         services.AddSingleton<ISecurityAuditSink, TAuditSink>();
         services.TryAddScoped<IKomaguAuthorizationService, DefaultKomaguAuthorizationService>();
+        services.AddOptions<KomaguRoleOptions>();
+        return services;
+    }
+
+    /// <summary>
+    /// Configures the <see cref="RequireRoleAttribute"/> guard (role claim type, 403 vs 404 on denial).
+    /// Call after <c>AddKomaguAuthorization</c>.
+    /// </summary>
+    public static IServiceCollection ConfigureKomaguRoles(
+        this IServiceCollection services,
+        Action<KomaguRoleOptions> configure)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configure);
+        services.AddOptions<KomaguRoleOptions>().Configure(configure);
         return services;
     }
 }

package/remediate/authz/dotnet/tests/Komagu.Security.Authorization.Tests/MassAssignmentDtoTests.cs

@@ -0,0 +1,76 @@
+namespace Komagu.Security.Authorization.Tests;
+
+using System.Text.Json;
+using Xunit;
+
+/// <summary>
+/// Mass-assignment remediation example: replace whole-entity binding (or <c>[Bind(Include = "...")]</c>) with a
+/// request DTO that declares only the client-editable fields, then copy them onto the tracked entity explicitly.
+/// </summary>
+public class MassAssignmentDtoTests
+{
+    /// <summary>Persisted entity: Role, IsAdmin and Balance must never be client-writable.</summary>
+    public sealed class Customer
+    {
+        public int Id { get; set; }
+        public string Name { get; set; } = string.Empty;
+        public string Email { get; set; } = string.Empty;
+        public string Role { get; set; } = "customer";
+        public bool IsAdmin { get; set; }
+        public decimal Balance { get; set; }
+    }
+
+    /// <summary>Allow-list DTO: only the fields a customer may edit on their own profile.</summary>
+    public sealed record ProfileUpdateDto(string Name, string Email)
+    {
+        /// <summary>Explicit copy: privileged fields are not reachable from the request.</summary>
+        public void ApplyTo(Customer customer)
+        {
+            ArgumentNullException.ThrowIfNull(customer);
+            customer.Name = Name;
+            customer.Email = Email;
+        }
+    }
+
+    private static readonly JsonSerializerOptions WebJson = new(JsonSerializerDefaults.Web);
+
+    [Fact]
+    public void ProfileUpdate_WithPrivilegedFieldsInJson_ChangesOnlyAllowListedFields()
+    {
+        var customer = new Customer { Id = 7, Name = "Old", Email = "old@example.com", Role = "customer", IsAdmin = false, Balance = 10m };
+        const string attackerJson = """
+            {"id": 1, "name": "New Name", "email": "new@example.com", "role": "admin", "isAdmin": true, "balance": 999999}
+            """;
+
+        var dto = JsonSerializer.Deserialize<ProfileUpdateDto>(attackerJson, WebJson);
+        Assert.NotNull(dto);
+        dto!.ApplyTo(customer);
+
+        Assert.Equal("New Name", customer.Name);
+        Assert.Equal("new@example.com", customer.Email);
+        Assert.Equal(7, customer.Id);
+        Assert.Equal("customer", customer.Role);
+        Assert.False(customer.IsAdmin);
+        Assert.Equal(10m, customer.Balance);
+    }
+
+    [Fact]
+    public void ProfileUpdateDto_ExposesOnlyNameAndEmail()
+    {
+        var writable = typeof(ProfileUpdateDto).GetProperties().Select(p => p.Name).OrderBy(n => n, StringComparer.Ordinal);
+        Assert.Equal(new[] { "Email", "Name" }, writable);
+    }
+
+    [Fact]
+    public void WholeEntityBinding_IsTheVulnerablePattern()
+    {
+        // Contrast: deserializing straight into the entity lets the client set Role/IsAdmin/Balance.
+        const string attackerJson = """{"name": "x", "email": "x@example.com", "role": "admin", "isAdmin": true, "balance": 999999}""";
+
+        var bound = JsonSerializer.Deserialize<Customer>(attackerJson, WebJson)!;
+
+        Assert.Equal("admin", bound.Role);
+        Assert.True(bound.IsAdmin);
+        Assert.Equal(999999m, bound.Balance);
+    }
+}