@jagreehal/shepherd 0.3.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +5 -0
- package/README.md +41 -419
- package/THIRD_PARTY_NOTICES.md +11 -0
- package/lenses/dotnet/SKILL.md +32 -0
- package/lenses/go/SKILL.md +30 -0
- package/lenses/java/SKILL.md +31 -0
- package/lenses/nextjs/SKILL.md +33 -0
- package/lenses/node-api/SKILL.md +32 -0
- package/lenses/nx-monorepo/SKILL.md +30 -0
- package/lenses/observability/SKILL.md +18 -11
- package/lenses/owasp-asvs/SKILL.md +50 -0
- package/lenses/owasp-llm/SKILL.md +44 -0
- package/lenses/python/SKILL.md +32 -0
- package/lenses/react/SKILL.md +33 -0
- package/lenses/rust/SKILL.md +31 -0
- package/package.json +17 -8
- package/packs/dotnet.yml +6 -0
- package/packs/go.yml +6 -0
- package/packs/java.yml +6 -0
- package/packs/nextjs.yml +7 -0
- package/packs/node-api.yml +7 -0
- package/packs/nx-monorepo.yml +6 -0
- package/packs/observability.yml +6 -0
- package/packs/owasp-asvs.yml +6 -0
- package/packs/owasp-llm.yml +8 -0
- package/packs/python.yml +6 -0
- package/packs/react.yml +6 -0
- package/packs/rust.yml +6 -0
- package/skills/ci-repair/SKILL.md +6 -1
- package/skills/garden/SKILL.md +28 -3
- package/skills/garden/references/telemetry.md +50 -0
- package/skills/incident/SKILL.md +6 -1
- package/skills/lens-import/SKILL.md +185 -0
- package/skills/lens-import/references/conversion.md +96 -0
- package/skills/lens-import/scripts/check-import.mjs +154 -0
- package/skills/shepherd/SKILL.md +121 -6
- package/skills/shepherd/references/dispatch.md +12 -0
- package/skills/shepherd/references/models.md +20 -7
- package/skills/shepherd/references/policy.md +9 -5
- package/skills/shepherd/references/stories.md +102 -0
- package/skills/swarm/SKILL.md +16 -1
- package/skills/swarm/references/custom-lenses.md +50 -7
- package/skills/triage/SKILL.md +19 -0
- package/src/cli.ts +210 -16
- package/src/config.ts +137 -21
- package/src/garden-traces.ts +461 -0
- package/src/garden.ts +2 -1
- package/src/install.ts +3 -0
- package/src/lens.ts +159 -8
- package/src/notify.ts +138 -0
- package/src/stack.ts +121 -0
- package/src/trace.ts +180 -0
- package/templates/shepherd-audit.yml +178 -0
- package/templates/shepherd-incident.yml +180 -0
- package/templates/shepherd.yml +427 -0
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: java
|
|
3
|
+
description: Java and Spring rules for a code review. Flags code that leaks resources, breaks transactions, trusts input or falls over under load in ways the compiler and static analysers miss. Covers @Transactional pitfalls, N+1 queries and unbounded fetches, missing authorisation on endpoints, unvalidated request bodies, queries and commands built from input, unsafe deserialisation and XML parsing, resources not closed, swallowed exceptions, thread-unsafe shared state in singletons, blocking calls without timeouts, and entity or API contract changes. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# java
|
|
7
|
+
|
|
8
|
+
Spring hides a lot behind annotations, proxies and a thread pool. Review
|
|
9
|
+
whether this change gets the transaction, security and lifecycle behaviour it
|
|
10
|
+
assumes, keeps singleton beans free of request state, and bounds the work a
|
|
11
|
+
single request can cause.
|
|
12
|
+
|
|
13
|
+
## Review
|
|
14
|
+
|
|
15
|
+
- **transaction-boundary**: `@Transactional` sits on a public method called through the Spring proxy, with the propagation, read-only flag and rollback rules the code needs. Flag: `@Transactional` on a private method or a method called from the same class (self-invocation skips the proxy), a checked exception that should roll back but does not (`rollbackFor` missing), a remote call or message publish inside a long transaction, a read path writing in a `readOnly` transaction. Why: data is committed half-done, or not at all, with no error.
|
|
16
|
+
- **query-shape**: Repository calls fetch what the code uses, in a bounded number of queries. Flag: a lazy association accessed in a loop (N+1), `findAll()` on a table that grows, a list endpoint with no `Pageable` or limit, `FetchType.EAGER` added to an entity. Why: a page that ran 3 queries in test runs 3,000 in production.
|
|
17
|
+
- **endpoint-authz** [refuse]: Every new controller method is covered by the security configuration and checks the caller may act on the resource. Flag: a new path not matched by the `SecurityFilterChain` rules, `permitAll` widened, a method taking an id with no ownership or role check (`@PreAuthorize` or an explicit check), CSRF disabled for a cookie-authenticated app. Why: the endpoint is public or lets users act on each other's data.
|
|
18
|
+
- **validate-input**: Request bodies and parameters are validated at the controller (`@Valid` with constraints) and bound to DTOs, never to entities. Flag: a `@RequestBody` entity, a DTO with no `@Valid`, mass assignment of fields like `role` or `id`. Why: callers set fields the code never meant to expose.
|
|
19
|
+
- **injection** [refuse]: Queries take input through bind parameters, commands through `ProcessBuilder` argument lists, file paths through a containment check. Flag: string concatenation into JPQL, SQL, `@Query(nativeQuery=true)` or `JdbcTemplate`; `Runtime.exec` with a built string; SpEL or OGNL evaluated over input; `Paths.get(base, userInput)` without normalising and checking the prefix. Why: injection and path traversal.
|
|
20
|
+
- **unsafe-parsing** [refuse]: Untrusted data is never handed to Java serialisation, and XML parsers disable external entities. Flag: `ObjectInputStream.readObject` on network or user data, Jackson default typing (`enableDefaultTyping`, `@JsonTypeInfo(use = CLASS)`) on untrusted input, a `DocumentBuilderFactory` or `XMLInputFactory` without XXE protection. Why: remote code execution and file disclosure.
|
|
21
|
+
- **resource-close**: Streams, connections, readers, clients and executors are closed with try-with-resources or a lifecycle hook. Flag: a `Connection`, `InputStream` or `HttpClient` response not closed on every path, an `ExecutorService` created per request and never shut down. Why: pools and file handles exhaust under load.
|
|
22
|
+
- **exception-handling**: Exceptions are handled once, with their cause, and never swallowed. Flag: an empty `catch`, `catch (Exception e) { log.error(e.getMessage()); }` that drops the stack, `throw new RuntimeException("failed")` without the cause, catching `InterruptedException` without restoring the interrupt flag. Why: the failure leaves no trail, or a thread pool cannot shut down.
|
|
23
|
+
- **singleton-state**: Singleton beans (the Spring default) hold no request or user state in fields, and shared mutable state is thread-safe. Flag: a non-final field set per request in a `@Service` or `@Controller`, a `HashMap` or `SimpleDateFormat` shared across threads, a static mutable cache with no bound or eviction. Why: requests see each other's data under concurrency.
|
|
24
|
+
- **blocking-timeouts**: Outbound HTTP, database and messaging calls set connect and read timeouts, and blocking calls stay off reactive or event-loop threads. Flag: a `RestTemplate`, `WebClient`, `HttpClient` or JDBC pool with default (infinite) timeouts, `.block()` inside a WebFlux handler, `@Async` with the default unbounded executor. Why: one slow dependency exhausts the thread pool.
|
|
25
|
+
- **contract-change**: Changes to entity mappings, DTOs serialised to clients, and public interfaces are deliberate and paired with a migration. Flag: a renamed or removed entity field with no migration, a changed `@Column` or `@Table`, a JSON field renamed, an enum persisted as `ORDINAL` that gains a value in the middle. Why: existing data or clients break at deploy.
|
|
26
|
+
|
|
27
|
+
## Fix
|
|
28
|
+
|
|
29
|
+
- Prefer: constructor injection, DTOs with Bean Validation, Spring Data pagination and fetch joins or entity graphs, try-with-resources, and the repository's configured HTTP client beans.
|
|
30
|
+
- Never touch: the security configuration beyond the endpoint in the PR, build files (`pom.xml`, `build.gradle`), and generated sources.
|
|
31
|
+
- Escalate: `endpoint-authz` and `contract-change` breaks, changes to transaction propagation on shared services, and any database migration.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nextjs
|
|
3
|
+
description: Next.js rules for a code review, meant to be composed with the react lens. Flags App Router and Pages Router code that leaks data across the server/client boundary, skips authorisation, caches the wrong thing or ships too much to the browser. Covers route handlers and server actions without auth, middleware matchers that miss routes, server-only code reaching the client, props that serialise secrets, user data cached across users, dynamic APIs that break static rendering, redirects built from input, unvalidated action input, heavy client bundles, and metadata or image misuse. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# nextjs
|
|
7
|
+
|
|
8
|
+
Next.js decides per file where code runs and what gets cached. Review whether
|
|
9
|
+
this change keeps secrets and per-user data on the server, checks who is
|
|
10
|
+
asking at every entry point, and caches only what is the same for everyone.
|
|
11
|
+
React component rules belong to the react lens; this one covers what the
|
|
12
|
+
framework adds.
|
|
13
|
+
|
|
14
|
+
## Review
|
|
15
|
+
|
|
16
|
+
- **handler-auth** [refuse]: Every route handler (`app/**/route.ts`, `pages/api/**`) and every server action checks authentication and authorisation itself, for the resource it touches. Flag: a handler or action that reads or writes data with no session check, an ownership check missing on an id from the request, reliance on a page-level check that the endpoint does not repeat. Why: server actions and API routes are public HTTP endpoints anyone can call directly.
|
|
17
|
+
- **middleware-matcher**: Middleware that enforces auth or headers covers every route it means to. Flag: a `matcher` that excludes `/api`, a negative lookahead that also skips a new protected segment, a new route outside the matcher, auth enforced only in middleware with no check in the handler. Why: the protected route is reachable by skipping the matcher.
|
|
18
|
+
- **server-only-boundary**: Modules that read secrets, the database or server env are marked `import "server-only"` (or live where client code cannot import them), and `"use client"` files import none of them. Flag: a database client, ORM model or secret-reading helper imported from a client component, a `"use client"` added to a file that imports server code. Why: the build bundles it for the browser or fails late in production.
|
|
19
|
+
- **serialised-props** [refuse]: Data passed from a server component to a client component, or returned from `getServerSideProps`/`getStaticProps`, holds only what the client may see. Flag: a whole user or database row passed as a prop, password hashes, tokens or internal fields in props, a server action returning more than the caller needs. Why: every prop is serialised into the HTML payload, readable in view-source.
|
|
20
|
+
- **per-user-cache**: Responses and data that depend on the user, cookies or headers are not cached for everyone. Flag: `fetch` with `force-cache` or `revalidate` on a per-user request, `unstable_cache`/`"use cache"` wrapping a function that reads the session without the user in its key, a route segment marked static that reads cookies. Why: one user's data is served to the next.
|
|
21
|
+
- **stale-after-mutation**: A server action or route handler that changes data revalidates what shows it (`revalidatePath`, `revalidateTag`, `router.refresh()`). Flag: a mutation with no revalidation of cached pages or tags that list the changed data. Why: users see the old value after saving and retry.
|
|
22
|
+
- **action-input**: Server action and route handler input is parsed and validated at the boundary before use. Flag: `formData.get(...)` cast straight to a type, a JSON body spread into a database call, a search param used as a number without parsing. Why: anyone can post any shape to the endpoint.
|
|
23
|
+
- **open-redirect**: `redirect()`, `NextResponse.redirect` and `router.push` with a URL from the request go only to same-origin paths or an allow-list. Flag: `redirect(searchParams.get("next"))`, a `callbackUrl` passed through unchecked. Why: phishing through a trusted domain.
|
|
24
|
+
- **public-env** [refuse]: `NEXT_PUBLIC_*` variables hold only values safe to publish. Flag: a key, token, internal URL or credential under a `NEXT_PUBLIC_` name, a server secret renamed to `NEXT_PUBLIC_` to make a client component work. Why: Next.js inlines every `NEXT_PUBLIC_` value into the client bundle.
|
|
25
|
+
- **dynamic-api-placement**: `cookies()`, `headers()`, `searchParams` and `noStore` are read only in the segments that need them. Flag: a dynamic API added to a layout or a shared component that makes every page under it dynamic, a static marketing page turned dynamic by a helper call. Why: the whole subtree loses static rendering and caching, and latency jumps.
|
|
26
|
+
- **client-bundle-weight**: Large or browser-only dependencies (editors, charts, maps, PDF, date libraries with locales) load with `next/dynamic` or in a server component. Flag: a heavy library imported at the top of a client component on a common route, `"use client"` added high in the tree so a whole page becomes client code. Why: every visitor downloads and parses it on first load.
|
|
27
|
+
- **framework-primitives**: Pages use `next/image` with dimensions or `fill` and sizes, `next/link` for internal navigation, and `generateMetadata`/`metadata` for titles. Flag: a raw `<img>` for content images without dimensions, `<a href>` for internal routes in a client app, `remotePatterns` widened to `**`. Why: layout shift, full reloads, and an image optimiser anyone can use as a proxy.
|
|
28
|
+
|
|
29
|
+
## Fix
|
|
30
|
+
|
|
31
|
+
- Prefer: the repository's existing auth helper (`auth()`, `getServerSession`, its own wrapper) at the top of each handler or action, its validation schemas, `server-only` imports, and narrowing props to a view type.
|
|
32
|
+
- Never touch: `next.config.*`, middleware matchers beyond the route in the PR, caching defaults for the whole app, or the auth provider setup.
|
|
33
|
+
- Escalate: any `handler-auth`, `serialised-props` or `public-env` break that changes who can see data in production, changing a matcher, and moving a large subtree between server and client.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: node-api
|
|
3
|
+
description: Node.js HTTP service rules for a code review (Express, Fastify, Hono, Koa, NestJS). Flags handlers that skip auth, trust input, leak errors, hang or lose work. Covers middleware mount order, per-resource authorisation, unvalidated bodies and params, queries and commands built from input, error responses that leak internals, async errors that escape the handler, missing timeouts on outbound calls, unbounded bodies and lists, idempotency on retried writes, blocking the event loop, untyped request augmentation and unsafe CORS. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# node-api
|
|
7
|
+
|
|
8
|
+
An HTTP handler is a public function anyone on the network can call with any
|
|
9
|
+
input, at any rate. Review whether this change checks who is calling, rejects
|
|
10
|
+
input it cannot handle, answers without leaking how it works, and never leaves
|
|
11
|
+
the process hung or the data half-written.
|
|
12
|
+
|
|
13
|
+
## Review
|
|
14
|
+
|
|
15
|
+
- **mount-order** [refuse]: Auth, rate-limit and body-size middleware are registered before the routes they protect. Flag: a new router mounted above `app.use(auth)`, a route registered in a plugin that Fastify encapsulates outside the auth hook, an error handler mounted before the routes. Why: Express and friends run middleware in registration order, so the route is public.
|
|
16
|
+
- **resource-authz** [refuse]: A handler that reads or changes a resource by id checks the caller may act on that resource, not only that they are signed in. Flag: `findById(req.params.id)` returned or updated with no owner, tenant or role check; an admin action guarded only by authentication. Why: any signed-in user can read or change anyone's data (IDOR).
|
|
17
|
+
- **validate-input**: Body, params, query and headers are parsed with a schema at the boundary, and the handler uses the parsed value. Flag: `req.body` spread into a database write, `Number(req.query.limit)` with no bounds, a schema parsed but the raw body used afterwards, mass assignment of fields like `role` or `isAdmin`. Why: callers send shapes the code never expected.
|
|
18
|
+
- **injection** [refuse]: Queries, shell commands, file paths and URLs take input only through parameters, argument arrays and validated values. Flag: SQL or NoSQL query strings built with template literals, `exec` with interpolated input, `path.join(base, req.params.file)` with no containment check, a server-side fetch to a URL from the request. Why: injection, path traversal and SSRF.
|
|
19
|
+
- **error-leak**: Error responses carry a stable code and message, never stack traces, SQL, internal hostnames or the raw error object. Flag: `res.status(500).json(err)`, `res.send(err.message)` for unexpected errors, a framework's dev error page enabled by default. Why: attackers map the system from it, and clients come to depend on internal text.
|
|
20
|
+
- **async-error-path**: Every async handler's rejection reaches the framework's error handler. Flag: an `async` Express 4 handler with no wrapper or `next(err)`, a promise started in a handler and not awaited, `.catch(() => {})` that answers 200. Why: an unhandled rejection hangs the request or crashes the process.
|
|
21
|
+
- **outbound-timeout**: Calls to databases, HTTP services and queues set a timeout and handle its failure. Flag: `fetch` with no `signal`/`AbortSignal.timeout`, an HTTP client with no timeout, a database pool with no acquire or statement timeout, a retry loop with no limit or backoff. Why: one slow dependency holds every request open until the service falls over.
|
|
22
|
+
- **bounded-work**: Request bodies, uploads, list endpoints and batch inputs have limits. Flag: a JSON or raw body parser with no size limit, a list endpoint with no pagination or max page size, a batch endpoint that loops over unbounded input, a regex from or over user input that can backtrack. Why: one request can exhaust memory or CPU for everyone.
|
|
23
|
+
- **idempotent-writes**: A write the client or a queue can retry (payments, orders, emails, webhooks) is safe to repeat: an idempotency key, a unique constraint, or a check-and-insert in one transaction. Flag: a webhook handler that does work before checking it has seen the event, a POST that creates a duplicate on retry. Why: retries are normal, so duplicates reach production.
|
|
24
|
+
- **event-loop-block**: Request handlers do no synchronous heavy work. Flag: `fs.readFileSync`, `execSync`, `crypto.pbkdf2Sync`, large `JSON.parse` or sorting of unbounded data inside a handler. Why: every concurrent request waits behind it.
|
|
25
|
+
- **typed-request-context**: Data attached to the request (`req.user`, tenant, request id) is declared through the framework's typing (module augmentation, Fastify decorators, Hono variables) and read from that one place. Flag: `(req as any).user`, a second ad-hoc property for the same thing, reading a user from a header after auth already set it. Why: a renamed field type-checks and the auth check quietly reads `undefined`.
|
|
26
|
+
- **cors-credentials**: CORS allows only known origins when credentials are allowed. Flag: `origin: true` or reflecting `req.headers.origin` with `credentials: true`, `*` added to an authenticated API. Why: any site can make authenticated calls as the visitor.
|
|
27
|
+
|
|
28
|
+
## Fix
|
|
29
|
+
|
|
30
|
+
- Prefer: the repository's existing validation schemas, auth middleware, error handler and HTTP client wrapper; parameterised queries through its database layer; `AbortSignal.timeout`.
|
|
31
|
+
- Never touch: the server entry file's middleware order beyond the route in the PR, global error handling, CORS and rate-limit configuration.
|
|
32
|
+
- Escalate: `mount-order`, `resource-authz` and `cors-credentials` breaks, since they change who can call the service; changing a response's error shape that clients read; adding a new dependency.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nx-monorepo
|
|
3
|
+
description: Nx monorepo rules for a code review. Flags changes that break project boundaries or quietly switch off what keeps a monorepo honest. Covers deep imports past a project's public entry, circular project dependencies, shared contracts changed without their dependents, app code in shared libs, targets, inputs, outputs and cache settings that stop affected and caching from covering code, loosened tags and dependency constraints, path aliases that bypass boundaries, untagged projects, implicit dependency workarounds, environment and secrets in shared libs, and version drift between projects. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# nx-monorepo
|
|
7
|
+
|
|
8
|
+
A monorepo holds together because of its boundaries and its build graph.
|
|
9
|
+
Review whether this change keeps each project behind its public entry, keeps
|
|
10
|
+
the graph acyclic and accurate, and leaves the rules that enforce both intact.
|
|
11
|
+
|
|
12
|
+
## Review
|
|
13
|
+
|
|
14
|
+
- **public-entry**: Code imports another project only through its published entry (`@org/lib`, its `index.ts`). Flag: an import reaching into `libs/x/src/lib/...`, a relative path climbing into another project, a re-export of internals to get around the entry. Why: internals become a contract nobody agreed to, and refactors break distant apps.
|
|
15
|
+
- **no-cycles**: A new import keeps the project graph acyclic. Flag: lib A importing lib B when B already imports A, directly or through a third project; a cycle papered over with a lazy `import()`. Why: cycles break build order, caching and affected detection.
|
|
16
|
+
- **shared-contract**: A change to a shared lib's exported types, functions or behaviour updates every dependent in the same PR, or keeps the old shape. Flag: a renamed or removed export, a changed signature or return shape, with dependents untouched in the diff. Why: other apps break at their next build or, worse, at runtime.
|
|
17
|
+
- **lib-purity**: Shared libs hold code more than one app uses, with no app-specific logic. Flag: an app's route, feature flag, copy or business rule added to a shared or `util` lib; a shared lib importing from an app. Why: every app now carries and couples to one app's behaviour.
|
|
18
|
+
- **boundary-rules** [refuse]: Module boundary enforcement stays on and as strict as it was. Flag: `@nx/enforce-module-boundaries` disabled or downgraded, `depConstraints` widened (`onlyDependOnLibsWithTags: ['*']`), a project's tags changed to escape a constraint, an `eslint-disable` for the boundary rule. Why: the one check that keeps the architecture is gone, and nothing says so.
|
|
19
|
+
- **graph-accuracy**: Targets, `inputs`, `outputs`, `namedInputs` and cache settings in `project.json` or `nx.json` still cover every file that affects the result. Flag: inputs narrowed so a source, config or env change no longer invalidates the cache, outputs missing a build directory, `cache: false` or `parallel` changed with no reason, a target removed that CI's `nx affected` runs. Why: affected skips tests that should run, and caches serve stale builds.
|
|
20
|
+
- **alias-bypass**: `tsconfig` path aliases map to a project's public entry only. Flag: a new path mapping to a file deep inside another project, a wildcard alias (`@org/*`) to `libs/*/src/*`, an alias that duplicates a project under a second name. Why: aliases sidestep the boundary rule and the graph alike.
|
|
21
|
+
- **project-tags**: A new project declares its type and scope tags, and sits where its kind belongs. Flag: a new `project.json` with no `tags`, an app created under `libs/` or a lib under `apps/`. Why: untagged projects match no constraint, so boundaries do not apply to them.
|
|
22
|
+
- **implicit-dependencies**: Dependencies come from real imports. Flag: `implicitDependencies` added to force build order or to hide a missing import, `"*"` implicit dependencies, a target `dependsOn` reaching into an unrelated project. Why: the graph stops matching the code, and affected runs too much or too little.
|
|
23
|
+
- **lib-config**: Shared libs read configuration passed in by the app, never environment variables or secrets of their own. Flag: `process.env` read inside a shared lib, a hard-coded URL, key or tenant id in a lib, a `.env` added to a lib. Why: every app inherits one app's settings, and secrets spread across deployables.
|
|
24
|
+
- **version-drift**: Each dependency has one version across the workspace. Flag: a project `package.json` pinning a different version of a library the root already provides, a second copy of a framework or React, a new dependency added to a project instead of the root where the workspace keeps them. Why: duplicate copies break singletons and bloat bundles.
|
|
25
|
+
|
|
26
|
+
## Fix
|
|
27
|
+
|
|
28
|
+
- Prefer: exporting what a consumer needs from the lib's `index.ts`, moving shared code into a lib with the right tags, passing configuration in from the app, and the repository's Nx generators for new projects.
|
|
29
|
+
- Never touch: `nx.json` cache and task-runner settings, `depConstraints`, CI's affected commands, and generated files.
|
|
30
|
+
- Escalate: `boundary-rules`, `graph-accuracy` and `shared-contract` breaks, splitting or merging projects, and any new cross-project dependency the tags do not already allow.
|
|
@@ -1,26 +1,33 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: observability
|
|
3
|
-
description: Observability rules for a code review. Flags new code that production cannot see or that leaks through telemetry. Covers outbound calls without a span
|
|
3
|
+
description: Observability rules for a code review. Flags new code that production cannot see, debug or alert on, or that leaks through telemetry. Covers entry points and outbound calls without a span, trace context lost across services, queues and background work, errors that lose their cause, logs that are unstructured or not tied to the trace, requests that carry no identifiers, secrets or personal data in telemetry, silent data drops, unbounded names and labels, metrics no alert can use, renamed telemetry, telemetry setup that can crash the app or lose data on exit, and user-facing changes with no signal. Use as a review lens or as a stamp rule pack.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# observability
|
|
7
7
|
|
|
8
|
-
Production is where this code will fail. Review whether an on-call engineer
|
|
9
|
-
could see it fail, find the request,
|
|
10
|
-
|
|
8
|
+
Production is where this code will fail. Review whether an on-call engineer who
|
|
9
|
+
has never seen this code could see it fail, find the one request, follow it
|
|
10
|
+
across services and know why, from the telemetry alone, without the telemetry
|
|
11
|
+
itself leaking data, costing too much or taking the app down.
|
|
11
12
|
|
|
12
13
|
## Review
|
|
13
14
|
|
|
14
|
-
- **boundary-signal**:
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
15
|
+
- **boundary-signal**: Every new entry point (HTTP route, queue or event consumer, scheduled job, worker, CLI command) and every call that leaves the process (HTTP, database, cache, queue, model API, file or shell) runs inside a span, from framework instrumentation or the repository's tracing helper. Flag: a new route, consumer, job or outbound call outside any span. Why: an outage there is invisible.
|
|
16
|
+
- **context-propagation**: Trace context crosses every boundary the work does. Outbound HTTP goes through an instrumented client, a published message carries the context in its headers and its consumer continues or links it, and deferred work (a timer, an in-process queue, a fire-and-forget promise, `waitUntil`) runs inside the span that started it. Flag: a hand-built client that bypasses instrumentation, a message published without context, a consumer that starts a fresh root, a detached promise. Why: the trace breaks at the boundary, and so does the investigation.
|
|
17
|
+
- **error-context**: A caught or rethrown error keeps its cause (`new Error(msg, { cause })`), is recorded on the active span with status ERROR, and is logged once with the identifiers that find the request: ids, never payloads. Flag: an empty `catch`, a rethrow of a bare message, a log of `error.message` without the error, an error turned into a success response with no record, the same error logged at every layer. Why: the trail ends at the catch.
|
|
18
|
+
- **structured-logs**: Server code logs through the repository's structured logger with fields, at a level that matches what happened, and every line carries the trace and span id. Flag: interpolated log strings, `console.log` in server code, a second logger, a logger not wired to the trace, an error logged at info. Why: nobody can search, alert on or jump from a line of prose.
|
|
19
|
+
- **request-context**: A handler or job puts the bounded identifiers that find one request on its span or request-scoped logger (the wide event): tenant, user, order or job id, the outcome. A change that adds a decision to existing code (a branch, fallback, retry, cache hit or miss, flag variant, or a choice between providers or rules) records which way it went there, as a bounded value. Flag: a new handler whose span carries nothing beyond its route, or a new path through existing code that leaves no trace of having been taken. Why: the trace says what failed, not for whom or which way the code went.
|
|
20
|
+
- **no-sensitive-data**: Logs, span attributes, events and metric labels carry no secrets, tokens, passwords, cookies, whole request bodies or headers, or personal data beyond the ids the team has agreed to keep. Flag: logging a whole object built from user input, headers or credentials; an email, name, address or card field as an attribute. Why: telemetry becomes the leak.
|
|
21
|
+
- **silent-drop**: Code that skips, filters or discards records, gives up on a retry, times out, or falls back counts or logs what it dropped and why. Flag: a `continue`, default branch, swallowed timeout or fallback value that loses data without a trace. Why: data loss nobody notices.
|
|
22
|
+
- **bounded-attributes**: Span names, metric names and metric labels take bounded values: route templates, not URLs; an enum reason, not an error message. Ids belong on span attributes and logs, never in a span name or metric label. Flag: user ids, ids inside URLs, free text or raw input as a metric label or span name. Why: cardinality blows up cost and queries.
|
|
23
|
+
- **alertable-signal**: A new dependency, queue, job or money or auth path emits what an alert needs to isolate it: outcomes counted by a bounded result or reason, a duration histogram, and for queues and jobs the lag or last success. Flag: a new integration whose failures show up only as a generic 500, a job nobody would notice had stopped. Why: no one can page on it, so no one is paged.
|
|
20
24
|
- **feature-signal**: A change meant to move a user outcome emits the event or metric that shows whether it did. Flag: a new user-facing flow with no event or metric. Why: no one can tell it works.
|
|
25
|
+
- **telemetry-contract**: Span names, attribute keys, metric names and labels, and event names are a contract that dashboards, alerts and queries read. Flag: a renamed or removed name or key with no note of what reads it, a unit changed under the same metric name. Why: the dashboard goes quiet and nobody notices until the incident.
|
|
26
|
+
- **safe-telemetry**: Telemetry can neither take the app down nor lose what it buffered. Initialisation runs once, at startup, before the code it instruments, and an exporter or backend failure never throws into a request. The process flushes on shutdown, and short-lived work (serverless handlers, workers, CLIs, scripts) flushes before it exits. Every deployable sets its service name, version and environment from configuration. Flag: telemetry initialised inside a request or module that loads late, `process.exit` with no flush, a signal handler that does not wait for shutdown, a new deployable with no service name or version, an environment hard-coded per build. Why: the telemetry is missing exactly when the process is dying.
|
|
27
|
+
- **telemetry-config**: A change to sampling, exporters, redaction or log level keeps errors and slow requests sampled, keeps redaction on and keeps production at its agreed level. Flag: sampling that can drop error traces, redaction switched off, debug logging enabled in production, an exporter endpoint or key hard-coded. Why: the telemetry a team relied on is gone and nothing says so.
|
|
21
28
|
|
|
22
29
|
## Fix
|
|
23
30
|
|
|
24
31
|
- Prefer: the repository's existing logger, tracer and metrics helpers, found in code next to the change.
|
|
25
32
|
- Never touch: telemetry configuration, exporters, sampling or vendor setup.
|
|
26
|
-
- Escalate: adding a logging, tracing or metrics dependency or vendor,
|
|
33
|
+
- Escalate: adding a logging, tracing or metrics dependency or vendor, any rule where the repository has no logger or tracer yet, and `telemetry-config` and `telemetry-contract` breaks: they are the team's calls.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: owasp-asvs
|
|
3
|
+
description: >
|
|
4
|
+
OWASP ASVS 5.0 rules for a code review, in any language or framework. Flags
|
|
5
|
+
changes that break an ASVS requirement a diff can show: injection, output
|
|
6
|
+
encoding, SSRF, unsafe parsing, server-side validation and mass assignment,
|
|
7
|
+
business-flow atomicity, rate limits, file uploads and paths, cookies,
|
|
8
|
+
sessions, token validation, authorization at function, object and field level,
|
|
9
|
+
password storage, account enumeration, cryptography, secrets and transport,
|
|
10
|
+
data exposure, error leakage and fail-open handling, and security event
|
|
11
|
+
logging. Each finding cites the ASVS requirement and CWE. Use as a review lens
|
|
12
|
+
or as a stamp rule pack.
|
|
13
|
+
source: github:OWASP/secure-agent-playbook/plugins/code-security-skills/skills/security-guidance@65d4efd2cd0b081d52101e9708792b944e4ddebb
|
|
14
|
+
license: CC-BY-4.0
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# owasp-asvs
|
|
18
|
+
|
|
19
|
+
Review the change against the OWASP Application Security Verification Standard
|
|
20
|
+
5.0, whatever the stack. Each rule names the requirements it checks, so a
|
|
21
|
+
finding reads as a traceable ASVS gap. Cite the requirement id with the rule id.
|
|
22
|
+
The full requirement text lives in the source under `data/asvs/V<chapter>.md`.
|
|
23
|
+
|
|
24
|
+
## Review
|
|
25
|
+
|
|
26
|
+
- **injection** [refuse]: Untrusted data reaches a query, shell, LDAP, XPath, template or evaluator only as a bound parameter. Flag: a query or command built by concatenation, eval or SpEL on input, a template compiled from input. Why: injection. (ASVS 1.2.4, 1.2.5, 1.3.2, 1.3.7, CWE-74)
|
|
27
|
+
- **output-encoding**: Output is encoded for its context (HTML, attribute, JS or JSON, URL, header), and a URL from input allows only http(s). Flag: input concatenated into markup or script, a `javascript:` link. Why: XSS. (ASVS 1.2.1-1.2.3, CWE-79)
|
|
28
|
+
- **ssrf** [refuse]: A server-side request to a URL or host from input checks scheme, host and port against an allowlist and follows no redirect. Flag: fetching a user-supplied URL. Why: internal services and cloud metadata exposed. (ASVS 1.3.6, 15.3.2, CWE-918)
|
|
29
|
+
- **unsafe-parsing** [refuse]: XML parsers disable external entities, and untrusted data deserializes into allowlisted types or plain data. Flag: default XML parser settings, native object deserialization of request data. Why: XXE and code execution. (ASVS 1.5.1, 1.5.2, CWE-611, CWE-502)
|
|
30
|
+
- **server-validation**: The server validates input against allowlists and ranges and binds only permitted fields. Flag: a check enforced only in the client, a request body bound whole to a model. Why: tampering and mass assignment. (ASVS 2.2.1, 2.2.2, 15.3.3, CWE-20, CWE-915)
|
|
31
|
+
- **atomic-flow**: Multi-step flows enforce their order, a business operation commits or rolls back whole, and a check and the action it guards run atomically. Flag: a skippable step, writes outside a transaction, check-then-act on stock or balance. Why: double spends. (ASVS 2.3.1, 2.3.3, 2.3.4, 15.4.2, CWE-367)
|
|
32
|
+
- **rate-limit**: Login, reset, signup, messaging and costly endpoints carry anti-automation limits. Flag: a new such endpoint with no limit. Why: brute force and quota drain. (ASVS 2.4.1, 6.3.1, CWE-307, CWE-770)
|
|
33
|
+
- **file-handling** [refuse]: Uploads cap size, check extension and content, and paths come from internal ids or stay under a fixed root; archives cap size and entry count and ignore entry paths. Flag: a user filename in a path. Why: traversal and zip slip. (ASVS 5.2.1-5.2.3, 5.3.2, 5.3.3, CWE-22, CWE-434)
|
|
34
|
+
- **cookie-flags**: Session cookies set Secure, HttpOnly and SameSite, with a `__Host-` prefix when not shared. Flag: a session cookie missing a flag. Why: theft and CSRF. (ASVS 3.3.1, 3.3.2, 3.3.4, CWE-614)
|
|
35
|
+
- **session-lifecycle**: Login issues a new session token from a CSPRNG, and logout or account disable invalidates it on the server. Flag: a reused session id, a logout that only clears the cookie. Why: fixation and replay. (ASVS 7.2.3, 7.2.4, 7.4.1, 7.4.2, CWE-384, CWE-613)
|
|
36
|
+
- **token-validation** [refuse]: Self-contained tokens verify their signature with an allowlisted algorithm and a preconfigured key, then `exp`, `nbf`, audience and type. Flag: decode without verify, `alg: none`, a key URL from the token. Why: forged identity. (ASVS 9.1.1-9.1.3, 9.2.1-9.2.3, CWE-347)
|
|
37
|
+
- **access-control** [refuse]: The server checks the caller's permission for each function, object and field it reads or writes. Flag: a new route or query with no check, a lookup by id without an owner filter. Why: IDOR and privilege escalation. (ASVS 8.2.1-8.2.3, 8.3.1, CWE-639, CWE-862)
|
|
38
|
+
- **password-storage** [refuse]: Passwords hash with argon2id, scrypt, bcrypt or PBKDF2 and verify exactly as typed, with 64+ characters allowed. Flag: a fast hash, truncation or lower-casing. Why: offline cracking. (ASVS 11.4.2, 6.2.8, 6.2.9, CWE-916)
|
|
39
|
+
- **account-enumeration**: Login, signup and reset answer the same for known and unknown accounts. Flag: "user not found", a different status code or timing. Why: account discovery. (ASVS 6.3.8, CWE-204)
|
|
40
|
+
- **approved-crypto**: Encryption uses authenticated modes with unique nonces, hashing avoids MD5 and SHA-1, secrets and ids come from a CSPRNG. Flag: ECB, a fixed IV, `Math.random` for a token. Why: broken confidentiality. (ASVS 11.3.1-11.3.4, 11.4.1, 11.5.1, CWE-327, CWE-338)
|
|
41
|
+
- **secret-transport**: Secrets come from a secret store, never code or URLs, and outbound calls use verified TLS. Flag: a key literal, a token in a query string, verification off. Why: leaks. (ASVS 13.3.1, 14.2.1, 12.2.1, CWE-798, CWE-319)
|
|
42
|
+
- **data-minimisation**: Responses return only needed fields, and sensitive data skips trackers and shared caches. Flag: a whole record serialized to the client. Why: exposure. (ASVS 15.3.1, 14.2.2, 14.2.3, CWE-200)
|
|
43
|
+
- **fail-closed**: Clients get generic errors, and an exception in validation or authorization denies. Flag: a stack trace or query in a response, a catch that proceeds. Why: leakage and fail-open. (ASVS 16.5.1, 16.5.3, 13.4.2, CWE-209, CWE-636)
|
|
44
|
+
- **security-events**: Authentication outcomes and authorization failures are logged with who and what, without secrets. Flag: a new auth path with no log. Why: attacks go unseen. (ASVS 16.3.1-16.3.3, CWE-778)
|
|
45
|
+
|
|
46
|
+
## Fix
|
|
47
|
+
|
|
48
|
+
- Prefer: the framework's parameterized queries, encoders, session, token and password-hashing APIs, and the repository's existing authorization helper.
|
|
49
|
+
- Never touch: cryptographic keys, secret stores, identity provider configuration.
|
|
50
|
+
- Escalate: `access-control`, `token-validation`, `password-storage`, `session-lifecycle` and `approved-crypto` changes that alter an existing contract, and any new dependency.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: owasp-llm
|
|
3
|
+
description: >
|
|
4
|
+
OWASP LLM Top 10 (2025) and Agentic Top 10 (2026) rules for a code review of
|
|
5
|
+
code that calls a model, runs an agent or serves MCP tools, in any language.
|
|
6
|
+
Flags untrusted content mixed into instructions, model output used as code,
|
|
7
|
+
SQL, HTML or a command, tools with more power than their job, destructive
|
|
8
|
+
actions without a person's approval, secrets and personal data in prompts,
|
|
9
|
+
poisoned retrieval and memory, unbounded tokens and loops, MCP servers without
|
|
10
|
+
auth or scoped tools, unpinned models and tools, agent-to-agent trust, and
|
|
11
|
+
answers presented as fact without grounding. Each finding cites the LLM or ASI
|
|
12
|
+
id. Use as a review lens or as a stamp rule pack.
|
|
13
|
+
source: github:OWASP/secure-agent-playbook/plugins/ai-security-skills@65d4efd2cd0b081d52101e9708792b944e4ddebb
|
|
14
|
+
license: CC-BY-4.0
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# owasp-llm
|
|
18
|
+
|
|
19
|
+
Review a change to code that builds prompts, calls a model, runs an agent loop,
|
|
20
|
+
defines tools or serves an MCP server. Treat everything the model reads as
|
|
21
|
+
attacker-controlled once any untrusted text reaches it, and everything the
|
|
22
|
+
model writes as untrusted input. Cite the OWASP id with the rule id.
|
|
23
|
+
|
|
24
|
+
## Review
|
|
25
|
+
|
|
26
|
+
- **instruction-boundary**: Untrusted text (user input, documents, web pages, emails, tool results) enters the prompt fenced as data, apart from system instructions. Flag: user or retrieved text concatenated into the system prompt, tool output fed back with no boundary. Why: prompt injection and goal hijack. (LLM01, ASI01)
|
|
27
|
+
- **output-as-input** [refuse]: Model output passes through the same validation, encoding and parameterization as user input before it reaches a shell, interpreter, query, HTML, file path or URL. Flag: `eval` or `exec` of generated code outside a sandbox, generated SQL run as is, model text rendered as raw HTML or Markdown with images. Why: injection and code execution. (LLM05, ASI05)
|
|
28
|
+
- **least-agency** [refuse]: Each tool does one narrow job with typed, constrained parameters and runs with the caller's permissions. Flag: a tool taking a free-form shell command, SQL, path or URL, a tool with a service account broader than the user's. Why: one injected instruction gains everything the tool can do. (LLM06, ASI02, ASI03)
|
|
29
|
+
- **human-approval**: Destructive, financial, external-send or permission-changing tool calls wait for a person's confirmation the model cannot supply. Flag: delete, pay, email or deploy executed straight from a model decision. Why: an injected goal acts unchecked. (LLM06, ASI09)
|
|
30
|
+
- **prompt-secrets**: Prompts, tool descriptions and system messages hold no keys, credentials, internal URLs or personal data beyond what the task needs. Flag: an API key or connection string in a prompt, a whole customer record sent to a model. Why: leakage and system prompt extraction. (LLM02, LLM07)
|
|
31
|
+
- **retrieval-scope**: Retrieval and vector queries filter by the caller's permissions, and ingested documents come from a known source. Flag: a vector search with no tenant or ACL filter, user uploads indexed into a shared store. Why: data leaks across users and poisoned context. (LLM04, LLM08)
|
|
32
|
+
- **memory-integrity**: Persistent agent memory records its source, stays scoped per user or session, and holds no instructions written by untrusted input. Flag: model output written to shared memory, memory replayed into later sessions as trusted. Why: one poisoned turn steers future runs. (ASI06)
|
|
33
|
+
- **bounded-consumption**: Model calls set max tokens and a timeout, agent loops cap steps and tool calls, and per-user rate or budget limits apply. Flag: a loop until the model says done, no `max_tokens`, user-chosen context size. Why: cost and denial of service. (LLM10, ASI08)
|
|
34
|
+
- **mcp-auth** [refuse]: An MCP server on HTTP or SSE authenticates clients, validates Origin, uses TLS and restricts CORS, and its tools reach only the paths and hosts they need. Flag: a network transport with no auth, a file tool with no root, a fetch tool that can reach internal addresses. Why: anyone on the network drives the tools. (LLM06, ASI02)
|
|
35
|
+
- **tool-description**: Tool names, descriptions and schemas state exactly what the tool does and carry no instructions to the model. Flag: a description broader or narrower than the code, imperative text aimed at the model. Why: tool poisoning and misuse. (LLM01, ASI02)
|
|
36
|
+
- **pinned-supply**: Models, MCP servers, tools and prompt packages are pinned to a version or digest from a trusted source, and the client passes each server only the env vars it needs. Flag: `latest`, a server launched through `npx` unpinned, the whole environment passed to a server. Why: a swapped component takes over the agent. (LLM03, ASI04)
|
|
37
|
+
- **agent-trust**: Messages between agents are authenticated and validated like external input, and one agent's failure stops the chain. Flag: an agent acting on another's output as instructions, retries that loop between agents. Why: cascading compromise. (ASI07, ASI08, ASI10)
|
|
38
|
+
- **grounded-output**: Factual answers that drive decisions cite retrieved sources or say they are unverified, and code acting on them checks the result. Flag: generated values stored as fact, an answer shown with no source. Why: misinformation users trust. (LLM09, ASI09)
|
|
39
|
+
|
|
40
|
+
## Fix
|
|
41
|
+
|
|
42
|
+
- Prefer: the SDK's structured messages and tool schemas, enums over free text, the repository's existing validation, sandbox and auth helpers.
|
|
43
|
+
- Never touch: model provider keys, system prompts owned by another team, MCP client configuration outside the change.
|
|
44
|
+
- Escalate: `least-agency`, `human-approval` and `mcp-auth` changes that remove a control, new tools with write or network reach, and switching model providers.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: python
|
|
3
|
+
description: Python rules for a code review (services, workers, Django, FastAPI, Flask). Flags code that trusts input, loses errors, blocks or misbehaves under load in ways ruff and mypy miss. Covers queries and commands built from input, unsafe deserialisation, missing authorization on views, unvalidated input, swallowed exceptions, blocking calls in async code, outbound calls with no timeout, mutable defaults and module state shared across requests, ORM N+1 and unbounded queries, transactions that commit half the work, naive datetimes, and API and model contract changes. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# python
|
|
7
|
+
|
|
8
|
+
Python lets almost anything run, so the defects show up in production rather
|
|
9
|
+
than at build time. Review whether this change keeps input away from
|
|
10
|
+
interpreters, keeps errors visible, stays non-blocking where it is async, and
|
|
11
|
+
keeps state from leaking between requests.
|
|
12
|
+
|
|
13
|
+
## Review
|
|
14
|
+
|
|
15
|
+
- **injection** [refuse]: SQL takes input through parameters, commands through argument lists, file paths through a containment check. Flag: f-strings or `%` into `cursor.execute`, `text()` or `.raw()`/`.extra()`; `subprocess` with `shell=True` and input; `os.system`; `open(os.path.join(root, user_path))` with no check that the resolved path stays under root; `eval`/`exec` on input. Why: injection and path traversal.
|
|
16
|
+
- **unsafe-deserialization** [refuse]: Untrusted data never reaches `pickle`, `marshal`, `shelve`, `yaml.load` without `SafeLoader`, or `torch.load` without `weights_only=True`. Flag: unpickling a request body, cache value or uploaded file; `yaml.load(data)`. Why: remote code execution.
|
|
17
|
+
- **view-authz** [refuse]: Every new view, route or endpoint checks authentication and the caller's right to the resource. Flag: a Django view without `login_required`/permission classes where neighbours have them, a FastAPI route without the auth dependency, a lookup by id with no owner or tenant filter. Why: the endpoint is public or exposes other users' data.
|
|
18
|
+
- **validate-input**: Request data is parsed with the framework's schema (Pydantic, DRF serializers, Django forms) before use, and only declared fields are written. Flag: `request.json`/`request.POST` passed straight to a model constructor or `update(**data)`, a serializer with `fields = "__all__"` on a write path. Why: callers set fields like `is_staff` or `tenant_id`.
|
|
19
|
+
- **exception-handling**: Exceptions are caught narrowly, keep their cause, and are logged once with the traceback. Flag: bare `except:` or `except Exception: pass`, `raise NewError(...)` inside `except` without `from err`, `logger.error(str(e))` without `exc_info`, a broad catch that returns a default and hides a failure. Why: the cause of the incident is lost, or a real error becomes wrong data.
|
|
20
|
+
- **async-blocking**: `async def` code never makes blocking calls. Flag: `requests`, `time.sleep`, synchronous database drivers, file I/O or CPU-heavy work inside an `async def` view or task without `run_in_executor`/`to_thread`; a sync ORM call from async Django without `sync_to_async`. Why: one call stalls the event loop for every request.
|
|
21
|
+
- **outbound-timeout**: HTTP, database and queue calls set timeouts, and retries are bounded with backoff. Flag: `requests.get(url)` with no `timeout`, an `httpx` client with timeouts disabled, `while True` retry loops. Why: requests hang indefinitely and exhaust workers.
|
|
22
|
+
- **shared-state**: Nothing request-specific lives in mutable defaults, module globals or class attributes. Flag: `def f(items=[])` or `={}`, a module-level dict used as a cache with no bound or lock, request data stored on a class attribute or a global client mutated per request. Why: data leaks between calls and requests, and memory grows.
|
|
23
|
+
- **orm-query-shape**: ORM access fetches what the code uses in a bounded number of queries. Flag: related objects accessed in a loop without `select_related`/`prefetch_related`/`selectinload`, `.all()` on a growing table in a request, a list endpoint with no pagination, `len(queryset)` instead of `.count()`. Why: N+1 queries and memory that grows with the table.
|
|
24
|
+
- **transaction-scope**: Multi-step writes that must succeed together run in one transaction, and side effects (emails, tasks, webhooks) fire after commit. Flag: two related writes outside `transaction.atomic()`/a session transaction, a Celery task enqueued inside a transaction that might roll back (use `on_commit`). Why: half-written data, or a task that runs against a row that does not exist.
|
|
25
|
+
- **datetime-aware**: Datetimes are timezone-aware and in UTC at boundaries. Flag: `datetime.now()` or `utcnow()` for stored or compared times, comparing naive and aware values, parsing timestamps without a zone. Why: off-by-hours bugs around DST and across servers, or a `TypeError` at runtime.
|
|
26
|
+
- **contract-change**: Changes to models, serialised response shapes and public functions are deliberate and paired with a migration. Flag: a renamed or removed model field with no migration, a new non-null column with no default, a changed response key, a removed keyword argument in a shared module. Why: data or clients break at deploy.
|
|
27
|
+
|
|
28
|
+
## Fix
|
|
29
|
+
|
|
30
|
+
- Prefer: parameterised queries through the ORM or driver, the framework's schema and permission classes, `logger.exception`, `raise ... from err`, `httpx`/`requests` with explicit timeouts, and `transaction.on_commit`.
|
|
31
|
+
- Never touch: dependency pins (`pyproject.toml`, `requirements*.txt`, lockfiles), existing migrations, and settings modules beyond the change.
|
|
32
|
+
- Escalate: `view-authz` and `contract-change` breaks, new migrations, and any change to authentication or middleware settings.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: react
|
|
3
|
+
description: React rules for a code review. Flags component code that renders wrong, leaks, races or locks out users in ways the hooks lint cannot see. Covers state derived in effects, effects that race or never clean up, stale closures, unstable identities that defeat memoisation, keys that lose state, uncontrolled-to-controlled switches, server data copied into local state, HTML injected from untrusted input, secrets in client bundles, error and loading states left out, and interactive elements no keyboard or screen reader can use. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# react
|
|
7
|
+
|
|
8
|
+
A component is correct when it shows the right thing for every state it can
|
|
9
|
+
be in, and stops doing work once it is gone. Review whether this change keeps
|
|
10
|
+
each render a pure function of props and state, keeps effects for
|
|
11
|
+
synchronising with the outside world, and keeps every user able to reach what
|
|
12
|
+
it renders.
|
|
13
|
+
|
|
14
|
+
## Review
|
|
15
|
+
|
|
16
|
+
- **derived-state-effect**: Values computable from props or state are computed during render (or with `useMemo` when costly), never copied into state by an effect. Flag: `useEffect(() => setX(f(props.y)), [props.y])`, state that mirrors a prop, a chain of effects each setting state for the next. Why: an extra render with stale values on screen, and two sources of truth that drift.
|
|
17
|
+
- **effect-race**: An effect that fetches or subscribes ignores results that arrive after its inputs changed or the component unmounted: an `AbortController`, an `ignore` flag, or the data library's own cancellation. Flag: `fetch(...).then(setData)` in an effect with no abort or ignore, a subscription with no unsubscribe in the cleanup. Why: a slow old response overwrites the new one, and the user sees data for the wrong id.
|
|
18
|
+
- **effect-cleanup**: Every timer, listener, observer, socket or subscription an effect starts is stopped in its cleanup. Flag: `setInterval`, `addEventListener`, `new IntersectionObserver`, a WebSocket opened in an effect with no returned cleanup, or a cleanup that removes a different function than was added. Why: leaks and duplicate handlers that grow with every mount, doubled under Strict Mode.
|
|
19
|
+
- **stale-closure**: A callback stored for later (an interval, a listener, a debounced function, a ref callback) reads current state through the setter's updater, a ref, or its dependencies. Flag: a `setInterval` in a mount-only effect that reads state, `setCount(count + 1)` inside a long-lived callback, a `useCallback` with a deliberately trimmed dependency list. Why: the callback acts on the values from its first render, silently.
|
|
20
|
+
- **unstable-identity**: An object, array or function created during render and passed to a memoised child, a context value, or a dependency array is stabilised when its identity matters. Flag: `value={{ user, setUser }}` on a context provider, an inline object in a `useEffect` dependency list, a fresh callback into a `React.memo` child that the change made memoised. Why: every render re-runs the effect or re-renders every consumer, and the memoisation buys nothing.
|
|
21
|
+
- **key-identity**: List keys come from the item's stable identity. Flag: index keys on a list that can reorder, insert or delete; `Math.random()` or a fresh id generated during render; a key that changes when the item is edited. Why: React reuses the wrong component, so input text, focus and local state jump to another row.
|
|
22
|
+
- **controlled-switch**: An input stays either controlled or uncontrolled for its whole life. Flag: `value={maybeUndefined}`, `value` without `onChange` and without `readOnly`, `defaultValue` changed after mount expecting the input to follow. Why: React warns and the field stops reflecting state, so the user's edit or the reset is lost.
|
|
23
|
+
- **server-state-copy**: Data from the server lives in the data-fetching cache (React Query, SWR, the router's loader), not copied into `useState` or a global store. Flag: a query result copied into state on success, a store that holds fetched rows with no invalidation, a mutation that updates local state but not the cache. Why: screens disagree after a mutation, and refetches overwrite edits.
|
|
24
|
+
- **html-injection** [refuse]: `dangerouslySetInnerHTML`, `innerHTML`, `href`/`src` built from data, and `eval`-like APIs take only sanitised or trusted content. Flag: `dangerouslySetInnerHTML={{ __html: userText }}` with no sanitiser, a `javascript:` URL reachable from user input, markdown rendered to HTML without sanitising. Why: stored XSS runs as the signed-in user.
|
|
25
|
+
- **client-secret** [refuse]: Nothing secret reaches code that ships to the browser. Flag: an API key, private token or service credential in a component, a client-exposed env var (`VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`) holding a secret, a server-only module imported into a client component. Why: anything in the bundle is public.
|
|
26
|
+
- **async-states**: A component that loads or mutates data renders its loading, empty and error states, and disables or guards a submit while it is pending. Flag: a fetch with only a success branch, a list with no empty state, a submit button that can fire twice, an error swallowed into a blank screen with no error boundary. Why: users see nothing, retry, and create duplicates.
|
|
27
|
+
- **accessible-interaction**: Interactive elements are real controls with accessible names. Flag: `onClick` on a `div` or `span` with no role, tab stop and key handler; an icon-only button with no label; an image that carries meaning with no `alt`; a modal that does not move or trap focus; custom form fields with no associated label. Why: keyboard and screen-reader users cannot use the feature, a legal exposure as well as a defect.
|
|
28
|
+
|
|
29
|
+
## Fix
|
|
30
|
+
|
|
31
|
+
- Prefer: computing in render, the data library the repository already uses for server state, the existing design-system components for controls and dialogs, and the repository's sanitiser for HTML.
|
|
32
|
+
- Never touch: shared design-system components, lint configuration, or the data library's global client setup.
|
|
33
|
+
- Escalate: introducing a new state, data or sanitiser library; a change to a context's value shape that consumers outside the PR read; and any `client-secret` break, since the key must be rotated as well as removed.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: rust
|
|
3
|
+
description: Rust rules for a code review. Flags code that compiles and passes clippy but panics, blocks, leaks or breaks soundness in production. Covers unsafe blocks without a SAFETY argument, unwrap and expect on fallible input, panics across FFI, blocking calls in async code, locks held across await, unbounded channels and spawns, lost errors, integer overflow in release builds, untrusted deserialisation limits, SQL and commands built from input, and public API and serde changes. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# rust
|
|
7
|
+
|
|
8
|
+
The compiler proves memory safety outside `unsafe`; it does not prove the
|
|
9
|
+
program stays up. Review whether this change keeps every `unsafe` justified,
|
|
10
|
+
turns bad input into errors rather than panics, and keeps async code from
|
|
11
|
+
stalling the runtime.
|
|
12
|
+
|
|
13
|
+
## Review
|
|
14
|
+
|
|
15
|
+
- **unsafe-justified** [refuse]: Every `unsafe` block or `unsafe impl` (`Send`, `Sync`) carries a `// SAFETY:` comment naming the invariant that makes it sound, and the invariant actually holds in the code around it. Flag: a new `unsafe` with no SAFETY comment, a comment that restates the code, `transmute` between types without a documented layout guarantee, `get_unchecked` with no bounds argument, `unsafe impl Send` for a type holding `Rc` or a raw pointer. Why: unsoundness is undefined behaviour, the one failure Rust otherwise rules out.
|
|
16
|
+
- **no-panic-on-input**: Code that handles input, network data, files or configuration returns errors rather than panicking. Flag: `.unwrap()`, `.expect()`, indexing `v[i]`, slicing `&s[a..b]` on byte offsets, or `unreachable!()` on values that come from outside the program. Why: one malformed request aborts the task or the process.
|
|
17
|
+
- **ffi-panic**: A function called from C (`extern "C"`) or another language catches panics and turns them into an error code. Flag: an `extern "C" fn` that can panic with no `catch_unwind`, a callback passed to C that can unwind. Why: unwinding across FFI aborts the process or is undefined behaviour.
|
|
18
|
+
- **async-blocking**: Async code never blocks the executor thread. Flag: `std::fs`, `std::thread::sleep`, `std::sync::Mutex` held over work, a blocking database or HTTP client, or heavy CPU loops inside an `async fn` without `spawn_blocking`. Why: one blocked worker thread stalls every task scheduled on it.
|
|
19
|
+
- **lock-across-await**: No lock guard (std or `tokio::sync`) is held across an `.await` unless that is the intent and the lock is async. Flag: a `MutexGuard` alive across `.await`, `RefCell` borrows held across `.await`. Why: deadlocks, or futures that are not `Send` and fail far from the change.
|
|
20
|
+
- **bounded-async**: Channels and task spawning are bounded. Flag: `unbounded_channel` fed by external input, `tokio::spawn` per request item with no limit or `JoinSet`, a spawned task whose `JoinHandle` is dropped while its errors matter. Why: memory grows under load and failures vanish.
|
|
21
|
+
- **error-context**: Errors keep their source and context. Flag: `.map_err(|_| ...)` that drops the original error, `Box<dyn Error>` in a library's public API where callers need to match, `let _ = ` on a `Result` from a write or send, `.ok()` that hides a failure the caller should see. Why: the cause of the incident is gone from logs.
|
|
22
|
+
- **overflow**: Arithmetic on sizes, lengths, counts, money or values from input uses `checked_`, `saturating_` or `wrapping_` deliberately. Flag: `a + b`, `a * b` or `as` casts between integer widths on external values. Why: release builds wrap silently, producing wrong lengths and allocations.
|
|
23
|
+
- **untrusted-decode** [refuse]: Deserialisation of untrusted input sets size and depth limits and never trusts lengths from the data. Flag: `bincode` or similar with no size limit on network input, `Vec::with_capacity(len_from_input)`, reading a whole request body with no cap. Why: one small message allocates gigabytes.
|
|
24
|
+
- **injection** [refuse]: SQL takes input through bind parameters, commands through `Command::arg`, paths through a containment check. Flag: `format!` into a query string, `Command::new("sh").arg("-c").arg(input)`, `root.join(user_path)` without checking the result stays under root. Why: injection and path traversal.
|
|
25
|
+
- **public-contract**: Changes to public items, trait definitions and serde shapes are deliberate and versioned. Flag: a removed or renamed `pub` item, a new required trait method without a default, a changed `#[serde(rename)]`, removed `#[serde(default)]` on a stored type, a new variant on a public enum without `#[non_exhaustive]`. Why: downstream crates and stored data break.
|
|
26
|
+
|
|
27
|
+
## Fix
|
|
28
|
+
|
|
29
|
+
- Prefer: `?` with the repository's error type (`thiserror` in libraries, `anyhow` with `.context()` in binaries), `spawn_blocking`, `tokio::sync` primitives, bounded channels, and checked arithmetic.
|
|
30
|
+
- Never touch: `Cargo.toml` features and versions, `build.rs`, generated bindings, and `#![forbid(unsafe_code)]` or lint attributes.
|
|
31
|
+
- Escalate: any new or changed `unsafe` block, `public-contract` breaks, and changes to the async runtime configuration.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Agent skills that drive a PR to merge-ready: a review swarm, thread triage, CI repair, and a loop that hands the result to stamp.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": "github:jagreehal/shepherd",
|
|
@@ -15,6 +15,8 @@
|
|
|
15
15
|
"commands",
|
|
16
16
|
"examples",
|
|
17
17
|
"lenses",
|
|
18
|
+
"packs",
|
|
19
|
+
"templates",
|
|
18
20
|
"AGENTS.md",
|
|
19
21
|
"THIRD_PARTY_NOTICES.md"
|
|
20
22
|
],
|
|
@@ -32,17 +34,24 @@
|
|
|
32
34
|
"lint": "oxlint src",
|
|
33
35
|
"changeset": "changeset",
|
|
34
36
|
"version-packages": "changeset version",
|
|
35
|
-
"release": "changeset publish"
|
|
37
|
+
"release": "changeset publish",
|
|
38
|
+
"docs:dev": "bun run --cwd docs dev",
|
|
39
|
+
"docs:build": "bun run docs:check && bun run --cwd docs build && bun docs/scripts/check-built.ts",
|
|
40
|
+
"docs:check": "bun docs/scripts/check.ts",
|
|
41
|
+
"docs:preview": "bun run --cwd docs preview"
|
|
36
42
|
},
|
|
37
43
|
"devDependencies": {
|
|
38
44
|
"@changesets/cli": "^3.0.3",
|
|
39
|
-
"@oxlint/plugins": "1.
|
|
40
|
-
"@types/bun": "^1.
|
|
41
|
-
"
|
|
42
|
-
"
|
|
45
|
+
"@oxlint/plugins": "1.88.0",
|
|
46
|
+
"@types/bun": "^1.4.3",
|
|
47
|
+
"executable-stories-bun": "^0.1.0",
|
|
48
|
+
"executable-stories-formatters": "^1.27.0",
|
|
49
|
+
"oxlint": "1.88.0",
|
|
50
|
+
"typescript": "^7.0.2"
|
|
43
51
|
},
|
|
44
52
|
"dependencies": {
|
|
45
|
-
"
|
|
46
|
-
"
|
|
53
|
+
"autotel": "8.2.1",
|
|
54
|
+
"yaml": "^2.9.1",
|
|
55
|
+
"zod": "^4.6.7"
|
|
47
56
|
}
|
|
48
57
|
}
|
package/packs/dotnet.yml
ADDED
package/packs/go.yml
ADDED
package/packs/java.yml
ADDED
package/packs/nextjs.yml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Next.js apps; composes the react pack. Extend pinned: github:jagreehal/shepherd/packs/nextjs.yml@<sha>
|
|
2
|
+
extends: [packs/react.yml]
|
|
3
|
+
lenses:
|
|
4
|
+
nextjs:
|
|
5
|
+
skill: lenses/nextjs
|
|
6
|
+
applies_to: ['**/app/**', '**/pages/**', '**/middleware.{ts,js}', '**/next.config.*']
|
|
7
|
+
gate: escalate
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Node.js HTTP services (Express, Fastify, Hono, Koa, NestJS). Extend pinned: github:jagreehal/shepherd/packs/node-api.yml@<sha>
|
|
2
|
+
# Every JS/TS file by default: narrow applies_to to the service directories in your repository.
|
|
3
|
+
lenses:
|
|
4
|
+
node-api:
|
|
5
|
+
skill: lenses/node-api
|
|
6
|
+
applies_to: ['**/*.ts', '**/*.js', '**/*.mts', '**/*.mjs']
|
|
7
|
+
gate: escalate
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Nx monorepos: project boundaries and the build graph. Extend pinned: github:jagreehal/shepherd/packs/nx-monorepo.yml@<sha>
|
|
2
|
+
lenses:
|
|
3
|
+
nx-monorepo:
|
|
4
|
+
skill: lenses/nx-monorepo
|
|
5
|
+
applies_to: ['**/project.json', 'nx.json', 'libs/**', 'packages/**', '**/tsconfig*.json']
|
|
6
|
+
gate: escalate
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Production observability for any service. Extend pinned: github:jagreehal/shepherd/packs/observability.yml@<sha>
|
|
2
|
+
lenses:
|
|
3
|
+
observability:
|
|
4
|
+
skill: lenses/observability
|
|
5
|
+
applies_to: ['**/*.ts', '**/*.js', '**/*.go', '**/*.rs', '**/*.java', '**/*.cs', '**/*.py']
|
|
6
|
+
gate: escalate
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# OWASP ASVS 5.0 security requirements for any language. Extend pinned: github:jagreehal/shepherd/packs/owasp-asvs.yml@<sha>
|
|
2
|
+
lenses:
|
|
3
|
+
owasp-asvs:
|
|
4
|
+
skill: lenses/owasp-asvs
|
|
5
|
+
applies_to: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.mjs', '**/*.go', '**/*.rs', '**/*.java', '**/*.kt', '**/*.cs', '**/*.py', '**/*.rb', '**/*.php']
|
|
6
|
+
gate: escalate
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# OWASP LLM Top 10 and Agentic Top 10 for code that calls models, runs agents or serves MCP tools.
|
|
2
|
+
# Extend pinned: github:jagreehal/shepherd/packs/owasp-llm.yml@<sha>
|
|
3
|
+
# No applies_to: a file glob cannot tell which files call a model, so swarm's router picks this lens from its
|
|
4
|
+
# description. Add applies_to for the directories that hold your prompts, agents and tools to run it on every change there.
|
|
5
|
+
lenses:
|
|
6
|
+
owasp-llm:
|
|
7
|
+
skill: lenses/owasp-llm
|
|
8
|
+
gate: escalate
|
package/packs/python.yml
ADDED
package/packs/react.yml
ADDED