@ranimontagna/agent-toolkit 0.2.0 → 0.2.2

package/SECURITY.md

@@ -5,7 +5,9 @@ supply-chain changes need careful review.
 
 ## Reporting
 
-Open a GitHub security advisory or a private issue with:
+Email the maintainer at
+[raniellimontagna@hotmail.com](mailto:raniellimontagna@hotmail.com) instead of
+opening a public issue. Include:
 
 - affected version or commit;
 - exact command used;
@@ -13,12 +15,64 @@ Open a GitHub security advisory or a private issue with:
 - relevant logs with secrets removed.
 
 Do not paste tokens, private repository URLs or internal project names into
-public issues.
+public issues. The project does not define a response-time or remediation SLA.
 
-## Project Controls
+## Dependency Integrity
 
-- repository dependencies are locked by `pnpm-lock.yaml`;
-- external installer sources are pinned in `tools.lock.json`;
-- mutable sources are blocked unless `--allow-mutable-sources` is explicit;
-- CI runs lint, typecheck, tests, build, Gitleaks and dependency audit;
-- npm releases use trusted publishing through GitHub Actions OIDC.
+Repository dependencies resolve through `pnpm-lock.yaml`, and CI installs them
+with `--frozen-lockfile`. Dependency-audit jobs install with lifecycle scripts
+disabled before running the moderate-or-higher audit. See
+[Architecture](docs/ARCHITECTURE.md) for the CI boundary.
+
+## External-Source Provenance
+
+`tools.lock.json` is the source of truth for the external sources represented in
+the lock. Package sources use exact versions, Git sources use full commits, and
+RTK archives are checked against locked SHA-256 values. The RTK metadata URL may
+select another non-latest tagged release in the locked repository, but the
+downloaded archive must still pass the locked checksum.
+
+Two installer paths are not content-pinned by the lock: Superpowers delegates to
+runtime-native plugin or extension identifiers, and the official Antigravity
+installer is identity-gated to an HTTPS URL but is not pinned by checksum or
+commit. Source-identity changes, mutable versions, alternate lock files, and a
+different Antigravity URL require the explicit `--allow-mutable-sources` opt-in;
+that permission accepts the reviewed exception for one invocation rather than
+making it immutable. See [Architecture](docs/ARCHITECTURE.md) and
+[Configuration](docs/CONFIGURATION.md) for the complete boundaries.
+
+## Network Bounds
+
+Toolkit-owned HTTP fetch and download helpers share a 30-second total deadline,
+allow at most five redirects, reject HTTPS downgrades, and enforce response-size
+limits. Downloads use an exclusive partial file and become visible at the target
+path only after a complete response. External package managers, Git, and
+runtime-native plugin commands retain their own network behavior. See
+[Architecture](docs/ARCHITECTURE.md#transport-and-filesystem-security).
+
+## Filesystem Containment
+
+Agent Skills checkouts verify the fetched commit and contain requested skill
+roots inside the checkout. Toolkit-managed Custom Skill copies are staged before
+replacement. Manifest-backed uninstall removes only recorded direct children of
+recognized runtime roots after canonical-path and filesystem-identity checks;
+containment failures preserve the manifest for review or retry. See
+[Architecture](docs/ARCHITECTURE.md#manifest-and-lifecycle-boundary).
+
+## CI Security Gates
+
+CI runs the full lint, typecheck, unit, build, syntax, and integration gate on
+Node.js 24. Separate jobs scan full Git history with Gitleaks, audit dependencies
+without lifecycle scripts, and review pull-request dependency changes at
+moderate severity or higher. Contributor commands and suite ownership are in
+[Testing](docs/TESTING.md).
+
+## npm Provenance
+
+Tag-driven publication reruns the full gate, checks version and `main` ancestry,
+and grants only read-only repository contents plus `id-token: write`. The publish
+helper uses `npm publish --provenance --access public` and bounded registry
+verification retries; the workflow does not use a long-lived npm token. npm-side
+trusted-publisher setup and release recovery are documented in
+[Deployment and Releases](docs/DEPLOYMENT.md). Released project history remains
+available in the public [changelog](CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranimontagna/agent-toolkit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Personal AI agent toolkit installer for Claude Code, Codex CLI, OpenCode, Gemini CLI, Antigravity and graph-aware workflows.",
   "type": "module",
   "engines": {

package/skills/security/NOTICE.md

@@ -0,0 +1,9 @@
+# Security Skills Attribution
+
+These first-party Agent Toolkit skills are informed by public defensive
+security and reconnaissance patterns from
+[`uphiago/recon-skills`](https://github.com/uphiago/recon-skills), licensed
+under the MIT License. They are rewritten and narrowed for authorized,
+non-destructive application and code security reviews; the upstream agent
+instructions, operational infrastructure assumptions, scripts, and offensive
+workflows are not included.

package/skills/security/api-security-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: api-security-audit
+description: Use when reviewing an API for authorization gaps, unsafe input binding, token handling, CORS, or HTTP method configuration.
+metadata:
+  origin: Adapted from uphiago/recon-skills; first-party defensive rewrite.
+  tags: api, security, authorization, cors
+---
+
+# API Security Audit
+
+Review an API for configuration and authorization weaknesses without attempting
+to take over accounts, alter data, or bypass production controls.
+
+## When to Use
+
+- Reviewing REST, GraphQL, RPC, or webhook endpoints.
+- Investigating mass-assignment, BOLA/IDOR, CORS, JWT, or verb-tampering risk.
+- Assessing an API before release or after an authorization change.
+
+## Authorization Boundary
+
+Work only against a repository, local fixture, staging environment, or written
+test scope. Prefer source review and unit tests. Never send admin-changing
+payloads to a real account, brute-force tokens, or probe unrelated hosts.
+
+## Procedure
+
+1. Inventory routes, methods, auth middleware, schemas, tenant identifiers, and
+   generated API documentation.
+2. For every read and write operation, identify the server-side authorization
+   decision. Confirm that object ownership and tenant scope are checked after
+   loading the object, not inferred from client input.
+3. Inspect request binding. Flag direct persistence of request bodies where
+   privileged fields such as `role`, `ownerId`, `tenantId`, `verified`, or
+   `isAdmin` are not allowlisted.
+4. Review method handling, including `OPTIONS`, `HEAD`, `TRACE`, method
+   override headers, and routes that accept both GET and mutating verbs.
+5. Review JWT validation: fixed algorithm allowlist, issuer/audience checks,
+   key rotation, expiry, and rejection of unsigned or wrongly signed tokens.
+6. Review CORS. A wildcard origin alone is not a credential leak; require an
+   unsafe combination of origin reflection, credentials, and a sensitive
+   browser-readable response.
+7. Reproduce only with harmless fixtures: a second test user, a synthetic
+   object, and a request that must return `401` or `403`. Do not modify data.
+
+## Evidence Gate
+
+Report a finding only when the code path or a controlled fixture demonstrates
+the trust-boundary failure. A suspicious field name, decoded JWT, or permissive
+header is a lead, not proof.
+
+## Report
+
+Include endpoint or source location, required role, expected decision, observed
+decision, affected asset, minimal safe reproduction, impact, and remediation.
+Redact tokens, cookies, API keys, and personal data.
+
+## Common Mistakes
+
+- Treating client-side route hiding as authorization.
+- Calling `Access-Control-Allow-Origin: *` a credentialed CORS finding.
+- Using a real user's identifier instead of a synthetic fixture.
+- Recommending `alg:none` or privilege-changing payloads in production tests.

package/skills/security/cicd-security-audit/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: cicd-security-audit
+description: Use when reviewing CI/CD workflows, build pipelines, release automation, action dependencies, permissions, artifacts, or secret handling.
+metadata:
+  origin: Adapted from uphiago/recon-skills; first-party defensive rewrite.
+  tags: security, ci, cd, supply-chain
+---
+
+# CI/CD Security Audit
+
+Review pipeline configuration for privilege, injection, secret, and supply
+chain risks. Keep the assessment static or use isolated test branches.
+
+## When to Use
+
+- Reviewing GitHub Actions, GitLab CI, CircleCI, or release scripts.
+- Preparing a repository for trusted publishing or external contributions.
+- Investigating secrets in logs, unsafe artifacts, or unpinned actions.
+
+## Procedure
+
+1. Inventory workflow triggers, actors, environments, protected branches,
+   reusable workflows, runners, deployment credentials, and artifacts.
+2. Check least privilege. Each job should declare only required permissions;
+   pull-request workflows must not expose write tokens to untrusted code.
+3. Trace untrusted input from branch names, issue titles, PR fields, commit
+   messages, and changed files into shell commands, expressions, paths, and
+   scripts. Use environment variables and fixed argument arrays rather than
+   interpolation.
+4. Check third-party actions and downloaded tools for immutable commit pins,
+   checksum verification, provenance, and update ownership.
+5. Check secret handling: no echo/trace, no secrets in command-line arguments,
+   artifacts, caches, test snapshots, or fork-triggered jobs.
+6. Review artifact upload/download boundaries, retention, deployment gates,
+   environment approvals, and concurrency controls.
+7. Validate changes in a disposable branch with synthetic secrets and a dry-run
+   deployment. Never print or exfiltrate a real secret.
+
+## Evidence Gate
+
+Distinguish a theoretical permission from an reachable path. Show the trigger,
+job, permission/input flow, and affected asset. A floating action tag is a
+supply-chain risk, not proof of compromise.
+
+## Report
+
+Include workflow/job, trigger, trust boundary, vulnerable data flow, impact,
+safe reproduction or static evidence, and exact hardening. Redact secret names
+when they reveal sensitive architecture and never include values.
+
+## Common Mistakes
+
+- Treating every `pull_request_target` workflow as automatically vulnerable.
+- Calling a public CI log a secret leak without proving the value is sensitive.
+- Suggesting live deployment tests for a static workflow review.

package/skills/security/cloud-misconfiguration-audit/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: cloud-misconfiguration-audit
+description: Use when reviewing cloud storage, IAM, metadata access, network exposure, or deployment configuration for unauthorized access risk.
+metadata:
+  origin: Adapted from uphiago/recon-skills; first-party defensive rewrite.
+  tags: cloud, security, iam, storage
+---
+
+# Cloud Misconfiguration Audit
+
+Assess cloud exposure from configuration, policy, logs, and synthetic fixtures.
+The goal is to reduce unintended access, not to enumerate or exploit another
+tenant's infrastructure.
+
+## When to Use
+
+- Reviewing AWS, GCP, Azure, Supabase, Firebase, object storage, or IAM policy.
+- Checking deployment templates, public endpoints, metadata protections, or
+  container/cloud role boundaries.
+
+## Procedure
+
+1. Define account/project/subscription, region, environment, and read-only
+   credentials in scope. Confirm the audit identity and expected permissions.
+2. Inventory internet-facing services, buckets, databases, load balancers,
+   serverless functions, service accounts, workload identities, and secrets.
+3. Review IAM for wildcard principals/actions/resources, cross-account trust,
+   unused roles, privilege escalation paths, and production identities in CI.
+4. Review storage for public listing/read/write, predictable object paths,
+   insecure CORS, version history, logs, and sensitive metadata.
+5. Review metadata-service protections and container/task role boundaries in
+   source and infrastructure-as-code. Do not query a live metadata endpoint
+   unless the account owner explicitly provides an isolated fixture.
+6. Confirm findings with policy simulation, provider analyzer output, or a
+   synthetic object. Never download unrelated customer data or alter policy.
+7. Recheck after remediation with the same read-only identity and record the
+   before/after decision.
+
+## Evidence Gate
+
+Public policy syntax is not automatically exploitable. Prove the effective
+permission, resource scope, and data class. A provider-owned public identifier
+is not a credential.
+
+## Report
+
+Record provider/account alias, resource type and masked identifier, effective
+principal/action, data class, impact, remediation, and verification result.
+Keep account IDs, tokens, object names, and personal data to the minimum needed.
+
+## Stop Conditions
+
+Stop on customer data, cross-account access, write permission, or unexpected
+production impact. Preserve only metadata and notify the authorized owner.

package/skills/security/js-secrets-audit/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: js-secrets-audit
+description: Use when reviewing JavaScript bundles, source maps, frontend configuration, or generated assets for exposed credentials and internal endpoints.
+metadata:
+  origin: Adapted from uphiago/recon-skills; first-party defensive rewrite.
+  tags: javascript, security, frontend, secrets
+---
+
+# JavaScript Secrets Audit
+
+Inspect browser-delivered JavaScript and source maps for values that grant
+privilege or reveal sensitive internal systems. Public configuration is not
+automatically a secret, and all findings must be redacted.
+
+## When to Use
+
+- Reviewing a frontend build before release.
+- Investigating a suspected API key, JWT, private URL, or source-map exposure.
+- Auditing generated assets from a local build or authorized staging site.
+
+## Procedure
+
+1. Inventory emitted JS, maps, HTML bootstraps, runtime config, and public
+   environment variables. Prefer local build output.
+2. Search for high-signal patterns: private-key headers, bearer tokens, JWT
+   shapes, cloud access-key prefixes, database URLs, webhook secrets, and
+   internal hostnames. Treat regex matches as leads.
+3. Classify each value: public identifier, publishable key, short-lived token,
+   privileged credential, personal data, or internal endpoint.
+4. Confirm only through source/config ownership and documentation. Never call a
+   matched service, decode a real token, or test a credential.
+5. Report path, bundle offset/source line, secret class, masked fingerprint,
+   exposure scope, and rotation/removal action.
+6. Rebuild with proper environment separation, remove maps or sensitive config,
+   invalidate caches, rotate credentials when needed, and rescan.
+
+## Evidence Gate
+
+Regex alone is insufficient. A finding needs ownership/context showing that the
+value is sensitive or that the endpoint exposes protected functionality. Never
+place the value in reports, snapshots, tickets, chat, or terminal output.
+
+## Safe Masking
+
+Use only a short prefix/suffix or a one-way fingerprint, for example
+`sk_live_••••••••9f2a`; preserve enough context for the owner to locate it.
+
+## Common Mistakes
+
+- Reporting every Firebase/Supabase/public client key as a vulnerability.
+- Assuming minification makes a secret safe.
+- Downloading source maps from unrelated deployments.
+- Testing a suspected credential instead of rotating it through the owner.

package/skills/security/llm-agent-security-audit/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: llm-agent-security-audit
+description: Use when auditing an LLM, RAG, chatbot, or tool-using agent for prompt injection, data exfiltration, system-prompt leakage, or cross-tenant access.
+metadata:
+  origin: Adapted from uphiago/recon-skills; first-party defensive rewrite.
+  tags: security, llm, agents, prompt-injection
+---
+
+# LLM and Agent Security Audit
+
+Test trust boundaries around model instructions, retrieved content, tools, and
+tenant data. A refusal or unsafe sentence alone is not a vulnerability; require
+reproducible impact at the data or action layer.
+
+## When to Use
+
+- Reviewing an agent with browser, shell, filesystem, email, or API tools.
+- Assessing RAG/document ingestion, plugins, MCP tools, or multi-tenant chat.
+- Investigating prompt injection, system-prompt leakage, or tool exfiltration.
+
+## Procedure
+
+1. Map system/developer/user/retrieved instructions, tool schemas, credentials,
+   memory, tenant boundaries, and approval gates.
+2. Use synthetic canary data and a disposable account. Label every test input
+   and keep external callbacks under the auditor's control.
+3. Test indirect instructions in documents and web content for instruction/data
+   confusion. Verify whether the model can cause a tool action, not merely say
+   it would.
+4. Apply the run-twice rule for alleged prompt or system-message leakage. A
+   finding needs reproducible non-guessable content or a verifiable action.
+5. For exfiltration claims, require an authorized OOB callback containing only
+   the synthetic canary. Rendered Markdown or a model claim is not proof.
+6. Test cross-tenant retrieval with a value independently known to belong to a
+   second synthetic tenant. Do not use real customer data.
+7. Check tool permissions, argument validation, URL allowlists, confirmation
+   gates, output encoding, and audit logs. Recommend architectural controls,
+   not prompt-only mitigations.
+
+## Evidence Gate
+
+Confabulation, jailbreak compliance, a model repeating user input, and a generic
+refusal bypass are not findings without a trust-boundary consequence.
+
+## Report
+
+Include model/build, synthetic input, tool/data boundary, reproducibility,
+observable impact, logs or callback metadata, and mitigation. Never include
+system prompts, customer content, credentials, or harmful payloads verbatim.
+
+## Stop Conditions
+
+Stop if a test reaches real data, sends an uncontrolled external request, or
+would mutate a real system. Revoke test credentials and preserve minimal logs.

package/skills/security/source-leak-audit/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: source-leak-audit
+description: Use when checking an application, repository, build, or deployment for exposed source files, debug artifacts, backups, configuration, or secrets.
+metadata:
+  origin: Adapted from uphiago/recon-skills; first-party defensive rewrite.
+  tags: security, source-leak, debug, secrets
+---
+
+# Source Leak Audit
+
+Find accidentally published source and diagnostic artifacts while preserving
+confidentiality. The audit proves exposure and location without collecting or
+redistributing secret values.
+
+## When to Use
+
+- Reviewing a web deployment, static asset bucket, container image, or repo.
+- Investigating `.env`, source maps, backups, debug pages, directory listings,
+  stack traces, or exposed API documentation.
+
+## Procedure
+
+1. Establish the exact authorized asset and deployment scope.
+2. Inspect repository ignore rules, build output, Docker layers, release
+   artifacts, static hosting configuration, and server error handling.
+3. Search source and generated files for filenames and patterns such as
+   `.env`, `*.map`, `.git/`, `backup`, `debug`, `phpinfo`, private keys, and
+   connection strings. Record file path and line number, not values.
+4. For a controlled deployment, request only harmless metadata or a bounded
+   prefix sufficient to prove the artifact exists. Stop when sensitive content
+   is confirmed.
+5. Check whether the exposed value is active using the owning team's approved
+   rotation or revocation process. Do not use the credential to authenticate.
+6. Verify remediation by removing the artifact, invalidating caches, rotating
+   credentials, and confirming the safe response status.
+
+## Evidence Gate
+
+An accessible filename is not enough. Confirm the artifact contains relevant
+source/configuration or that a debug response exposes meaningful internals.
+Never include secret values, full cookies, private keys, or personal data in a
+report, terminal output, issue, or model context.
+
+## Report
+
+Record asset, path, response/build location, data class, exposure window if
+known, impact, containment action, and safe verification result. Use masked
+examples such as `DATABASE_URL=postgres://***`.
+
+## Do Not
+
+- Clone or archive an exposed private repository.
+- Download more content after confirming exposure.
+- Test leaked credentials against any service.
+- Treat a public client identifier as a secret without evidence of privilege.