evandro/dev-workflows
1
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

wip: snapshot das alterações não commitadas (2026-10-20)

Browse Source 
Origem: D:/Documents/Github/dev-workflows
Arquivos omitidos (segredos, bancos de dados, logs, >50 MB): 0
This commit is contained in:
evandro committed 2026-10-20 00:49:23 -03:00
1 parent c17192c9fe
commit 2ef6f6be10
61 files changed
+7892
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

skills/dependency-scanning/docs/fixer-policy.md
+111
View File
@@ -0,0 +1,111 @@
# Security Fixer Policy
This policy classifies security findings by how an agent may remediate them. Fixer-capable skills must use this policy before changing files, generating patches, or recommending an automated remediation path.
## Categories
### Auto-fix
The agent may apply the fix directly when the finding is high-confidence, the change is narrow, and the expected behavior is mechanically verifiable.
Criteria:
- The vulnerable pattern and target file are unambiguous.
- The fix is deterministic and follows an existing project convention or a well-known safe default.
- The change has low blast radius and does not alter public APIs, authorization semantics, data models, deployment topology, or runtime trust boundaries.
- The agent can run or define a concrete verification step.
Examples:
- Add missing security headers in a local framework configuration using the project's existing middleware pattern.
- Replace string-built SQL with parameter binding when the query shape and parameters are clear.
- Pin a container image tag or GitHub Action version when the intended version is known from lock files, release metadata, or existing repository conventions.
- Add a `.dockerignore` or `.gitignore` entry for `.env` files without removing or exposing secret values.
### Assisted-fix
The agent may prepare a patch or exact commands, but the user or repository owner must confirm context, run environment-specific checks, or choose among valid alternatives before merge.
Criteria:
- The finding is valid, but the best remediation depends on application behavior, deployment constraints, ownership boundaries, or compatibility requirements.
- Multiple safe remediation options exist.
- The change is moderate in scope or requires coordinated validation outside the local workspace.
- The agent can reduce the work to a reviewable patch, migration plan, configuration diff, or decision list.
Examples:
- Add authorization middleware to an endpoint when the correct role or ownership predicate needs product confirmation.
- Upgrade a vulnerable dependency across a major version boundary.
- Tighten CI permissions where release, package, or deployment jobs may need specific write scopes.
- Add Kubernetes `NetworkPolicy` rules where service communication requirements must be confirmed.
### Guidance-only
The agent must not modify files. It should explain the finding, risk, and recommended remediation path.
Criteria:
- The remediation requires organizational policy, architecture changes, vendor configuration, legal review, procurement, or manual operational work.
- The agent lacks access to the system that must be changed.
- The change cannot be represented safely as a local patch.
Examples:
- Adopt a centralized secrets manager across teams.
- Establish a vulnerability management SLA.
- Change cloud account guardrails, identity provider policy, or production firewall rules outside the repository.
- Resolve license obligations for GPL, AGPL, commercial, unknown, or no-license dependencies.
### Human-review-required
The agent must stop short of applying a fix and explicitly request human review before remediation proceeds.
Criteria:
- A hard gate below applies.
- The finding involves sensitive credentials, production access, destructive operations, legal/compliance interpretation, or security-critical logic.
- The agent cannot confidently preserve intended behavior.
- The evidence is incomplete or the finding may be a false positive with material operational impact.
Examples:
- Rotate leaked credentials or revoke certificates.
- Change authentication, authorization, cryptography, payment, medical, safety, or tenant-isolation logic.
- Modify production deployment, incident response, or containment procedures.
- Apply a remediation that deletes data, removes audit evidence, weakens controls, or accepts risk.
## Decision Criteria
Classify each finding using the most restrictive category that applies.
1. Confirm the finding is in scope for the skill and supported by concrete evidence.
2. Determine whether any hard gate forces human review.
3. Estimate blast radius: local config or code path, cross-cutting application behavior, infrastructure, production operations, or organizational policy.
4. Check remediation confidence: deterministic patch, multiple valid options, missing context, or uncertain behavior.
5. Check verification: automated test or scan, manual validation, external approval, or no reliable verification available.
6. Choose the category:
- Use auto-fix only when evidence, scope, remediation, and verification are all strong.
- Use assisted-fix when a patch is useful but context or approval is required.
- Use guidance-only when local code changes are not the right remediation vehicle.
- Use human-review-required whenever a hard gate applies or safe behavior preservation is uncertain.
## Hard Gates for Human Review
Any of these conditions forces `human-review-required`:
- Secret exposure requiring credential rotation, revocation, certificate replacement, or git history rewriting.
- Authentication, authorization, session management, cryptographic, payment, tenant isolation, or safety-critical logic changes.
- Production infrastructure, network, identity, IAM, deployment, incident response, or data retention changes.
- Destructive or irreversible actions, including deleting data, rewriting history, disabling audit logs, removing evidence, or changing backups.
- Legal, compliance, privacy, or license-risk decisions.
- Changes requiring owner-specific business rules, threat model assumptions, regulatory interpretation, or risk acceptance.
- Unclear ownership, missing tests for a high-impact path, conflicting framework guidance, or evidence that the finding may be a false positive.
- Any remediation that would weaken an existing security control to make a tool pass.
## Fixer Workflow Review Gates
Fixer-capable workflows must pass these gates before any applied patch is considered ready for handoff:
1. **Scope gate:** State the files, settings, and behaviors that are in scope; avoid unrelated refactors, formatting churn, dependency updates, or opportunistic cleanup.
2. **Approval gate:** Request explicit approval before assisted-fix or human-review-required work proceeds, and before any change that affects hard-gated areas even when a patch can be drafted.
3. **Review gate:** Provide reviewer evidence that includes the finding, policy category, changed files, behavior-change risk, verification performed or still required, and any assumptions the reviewer must confirm.
4. **Rollback gate:** Provide rollback guidance for every proposed or applied change, including the exact revert path when local patches are used or the operational rollback owner when the change cannot be reverted locally.
Applied fixes must be isolated to the smallest viable patch. If the agent discovers unrelated defects while fixing, it should report them separately instead of expanding the patch. If rollback is unclear, expensive, or depends on production state, classify the remediation as `human-review-required`.
## Skill Usage
Fixer-capable skills must reference this policy when producing remediation guidance or patches. Their workflows must include the review gates above and must not apply changes until the selected category allows it. The policy classifies the remediation path only; it does not change finding schemas or require new output fields.
skills/dependency-scanning/docs/normalized-json-output.md
+158
View File
@@ -0,0 +1,158 @@
# Normalized JSON Output Contract
SecuritySkills can emit machine-readable findings as a normalized JSON envelope
that validates against [`schemas/finding.schema.json`](../schemas/finding.schema.json).
This contract is independent of SARIF. Downstream systems may map it to SARIF,
ticketing systems, GRC platforms, dashboards, or vulnerability stores without
changing individual skill output rules.
See [`docs/sarif-output.md`](sarif-output.md) for the repo-level SARIF 2.1.0
export mapping.
## Envelope
Every JSON response uses this top-level shape:
```json
{
"schema_version": "1.0.0",
"run": {
"id": "run-2026-06-16T12:00:00Z",
"timestamp": "2026-06-16T12:00:00Z",
"tool": "codex",
"target": "github.com/example/service",
"source_ref": "commit-or-build-id"
},
"skill": {
"name": "secure-code-review",
"version": "1.0.0",
"path": "skills/appsec/secure-code-review/SKILL.md",
"frameworks": ["OWASP-ASVS-4.0.3", "CWE"]
},
"findings": []
}
```
- `schema_version` is fixed at `1.0.0` until a breaking contract change is
required.
- `run.id` is the deduplication boundary for one execution. Use an orchestrator
ID, CI job ID, or generated run ID.
- `run.timestamp` should be an ISO 8601 timestamp.
- `run.target` identifies the reviewed repository, project, service, artifact,
environment, or evidence package.
- `skill.name`, `skill.version`, and `skill.frameworks` come from the skill's
`SKILL.md` frontmatter.
## Findings
Each finding must include:
- `id`: stable finding ID within the run.
- `title`: concise finding title.
- `severity`: one of `info`, `low`, `medium`, `high`, or `critical`.
- `status`: one of `open`, `mitigated`, `accepted_risk`, or `false_positive`.
- `evidence`: one or more concrete evidence entries.
- `remediations`: one or more remediation recommendations, each with a test
strategy.
Each finding must include at least one framework/CWE mapping:
- `cwe`: array of CWE IDs such as `CWE-89`, when applicable.
- `framework_refs`: array of framework/control references from the skill's
declared frameworks.
Optional fields such as `fingerprint`, `description`, and `references` support
enterprise deduplication, analyst context, and external advisory linking.
## Evidence
Evidence entries must identify where the issue was observed and summarize the
observation. Locations may be source paths, line ranges, cloud resource IDs, log
sources, policy paths, scanner result identifiers, or evidence package records.
Use `snippet` only for the minimal redacted text needed to prove the finding.
Set `redacted: true` when secrets, tokens, personal data, internal hostnames, or
other sensitive values were removed.
## Remediation And Tests
Each remediation item must include:
- `guidance`: concrete remediation steps or patch guidance.
- `confidence`: `low`, `medium`, or `high`.
- `blast_radius`: expected affected files, systems, users, integrations, data,
or workflows.
- `behavior_change_risk`: `low`, `medium`, or `high`.
- `test_strategy`: validation that proves the issue is fixed.
`test_strategy` must include a `summary` and at least one of
`recommended_tests` or `generated_tests`. See
[`docs/remediation-output.md`](remediation-output.md) for remediation-specific
field guidance.
## Minimal Example
```json
{
"schema_version": "1.0.0",
"run": {
"id": "run-001",
"timestamp": "2026-06-16T12:00:00Z",
"tool": "codex",
"target": "payments-api",
"source_ref": "abc1234"
},
"skill": {
"name": "api-security",
"version": "1.0.0",
"path": "skills/appsec/api-security/SKILL.md",
"frameworks": ["OWASP-API-Top-10-2023", "CWE"]
},
"findings": [
{
"id": "API-SEC-001",
"fingerprint": "api-security:users-delete:missing-admin-auth",
"title": "Administrative endpoint lacks authorization check",
"description": "The delete-user route accepts authenticated requests without verifying administrative privileges.",
"severity": "high",
"status": "open",
"cwe": ["CWE-862"],
"framework_refs": [
{
"framework": "OWASP-API-Top-10-2023",
"control": "API5:2023",
"name": "Broken Function Level Authorization"
}
],
"evidence": [
{
"location": "routes/users.js:42",
"artifact_type": "source",
"summary": "DELETE /users/:id checks authentication but not administrator role.",
"snippet": "router.delete('/users/:id', requireAuth, deleteUser)",
"redacted": false
}
],
"remediations": [
{
"guidance": "Require an administrator role check before invoking deleteUser.",
"confidence": "high",
"blast_radius": "User administration routes only.",
"behavior_change_risk": "medium",
"test_strategy": {
"summary": "Proves non-admin users cannot delete accounts while admins still can.",
"recommended_tests": [
{
"name": "Reject non-admin delete",
"type": "integration",
"purpose": "Confirms the vulnerable authorization bypass no longer succeeds.",
"command": "npm test -- users-authz.test.js",
"expected_result": "Non-admin DELETE /users/:id returns 403 and admin DELETE succeeds."
}
]
}
}
]
}
]
}
```
skills/dependency-scanning/docs/sarif-output.md
+229
View File
@@ -0,0 +1,229 @@
# SARIF Output Mapping
SecuritySkills may emit SARIF-compatible JSON for tools that ingest Static
Analysis Results Interchange Format (SARIF) 2.1.0. SARIF output is an export
view of the normalized finding envelope documented in
[`docs/normalized-json-output.md`](normalized-json-output.md); it does not
replace the normalized JSON contract or change the required finding fields.
## Top-Level Shape
Use SARIF version `2.1.0` with the standard schema URI:
```json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "SecuritySkills",
"semanticVersion": "1.0.0",
"rules": []
}
},
"results": []
}
]
}
```
Use one `run` per normalized envelope. `run.tool.driver.name` should identify
SecuritySkills or the executing agent. `run.tool.driver.semanticVersion` should
use the skill version when a single skill produced the run.
## Mapping
Map normalized fields to SARIF as follows:
| Normalized field | SARIF field |
|---|---|
| `run.id`, `run.timestamp`, `run.target`, `run.source_ref` | `runs[].properties.securityskills.run` |
| `skill.name`, `skill.version`, `skill.path`, `skill.frameworks` | `runs[].tool.driver.name`, `runs[].tool.driver.semanticVersion`, `runs[].properties.securityskills.skill` |
| `finding.id` | `results[].ruleId` and `results[].properties.securityskills.finding_id` |
| `finding.fingerprint` | `results[].partialFingerprints.securityskillsFingerprint` |
| `finding.title` | `tool.driver.rules[].shortDescription.text` |
| `finding.description` | `tool.driver.rules[].fullDescription.text` and `results[].message.text` |
| `finding.severity` | `results[].level` |
| `finding.status` | `results[].properties.securityskills.status` |
| `finding.cwe` | `tool.driver.rules[].relationships` when supported, and `properties.securityskills.cwe` |
| `finding.framework_refs` | `tool.driver.rules[].properties.securityskills.framework_refs` |
| `finding.evidence` | `results[].locations` plus `properties.securityskills.evidence` |
| `finding.references` | `tool.driver.rules[].helpUri` or `tool.driver.rules[].properties.securityskills.references` |
| `finding.remediations` | `tool.driver.rules[].help.text` and `properties.securityskills.remediations`, including each remediation's `test_strategy` |
## Severity
SARIF `level` has fewer values than the normalized contract. Use this mapping:
| Normalized severity | SARIF level |
|---|---|
| `critical` | `error` |
| `high` | `error` |
| `medium` | `warning` |
| `low` | `note` |
| `info` | `note` |
Keep the original severity in
`results[].properties.securityskills.severity` so downstream systems can
preserve the distinction between `critical` and `high`.
## Locations
For source, configuration, policy, or scan-result evidence with file locations,
populate `results[].locations[].physicalLocation`:
```json
{
"physicalLocation": {
"artifactLocation": {
"uri": "routes/users.js"
},
"region": {
"startLine": 42
}
},
"message": {
"text": "DELETE /users/:id checks authentication but not administrator role."
}
}
```
If the normalized evidence location does not contain a parseable file path and
line number, still emit a SARIF result and store the original location under
`properties.securityskills.evidence`. For cloud resources, identities, network
assets, logs, or documents, use the best stable asset identifier as
`artifactLocation.uri` only when it is meaningful to the SARIF consumer.
## Rules
Create one `tool.driver.rules[]` entry per distinct `ruleId`. A rule should
include:
- `id`: the normalized `finding.id`, or a stable detector ID when multiple
findings share the same detection rule.
- `shortDescription.text`: the finding title or detector title.
- `fullDescription.text`: the finding description.
- `help.text`: remediation guidance and test strategy summary.
- `properties.securityskills`: CWE IDs, framework references, normalized
severity, and any remediation metadata that does not fit native SARIF fields.
Do not invent CWE, framework, or control identifiers for SARIF. Reuse only the
values already present in the normalized finding.
## Minimal Example
```json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "api-security",
"semanticVersion": "1.0.0",
"rules": [
{
"id": "API-SEC-001",
"shortDescription": {
"text": "Administrative endpoint lacks authorization check"
},
"fullDescription": {
"text": "The delete-user route accepts authenticated requests without verifying administrative privileges."
},
"help": {
"text": "Require an administrator role check before invoking deleteUser. Validate with integration tests for non-admin and admin delete flows."
},
"properties": {
"securityskills": {
"severity": "high",
"cwe": ["CWE-862"],
"framework_refs": [
{
"framework": "OWASP-API-Top-10-2023",
"control": "API5:2023",
"name": "Broken Function Level Authorization"
}
]
}
}
}
]
}
},
"results": [
{
"ruleId": "API-SEC-001",
"level": "error",
"message": {
"text": "Administrative endpoint lacks authorization check"
},
"locations": [
{
"physicalLocation": {
"artifactLocation": {
"uri": "routes/users.js"
},
"region": {
"startLine": 42
}
},
"message": {
"text": "DELETE /users/:id checks authentication but not administrator role."
}
}
],
"partialFingerprints": {
"securityskillsFingerprint": "api-security:users-delete:missing-admin-auth"
},
"properties": {
"securityskills": {
"finding_id": "API-SEC-001",
"severity": "high",
"status": "open",
"remediations": [
{
"guidance": "Require an administrator role check before invoking deleteUser.",
"confidence": "high",
"blast_radius": "User administration routes only.",
"behavior_change_risk": "medium",
"test_strategy": {
"summary": "Proves non-admin users cannot delete accounts while admins still can.",
"recommended_tests": [
{
"name": "Reject non-admin delete",
"type": "integration",
"purpose": "Confirms the authorization bypass no longer succeeds.",
"command": "npm test -- users-authz.test.js",
"expected_result": "Non-admin DELETE returns 403 and admin DELETE succeeds."
}
]
}
}
]
}
}
}
],
"properties": {
"securityskills": {
"run": {
"id": "run-001",
"timestamp": "2026-06-16T12:00:00Z",
"target": "payments-api",
"source_ref": "abc1234"
},
"skill": {
"name": "api-security",
"version": "1.0.0",
"path": "skills/appsec/api-security/SKILL.md",
"frameworks": ["OWASP-API-Top-10-2023", "CWE"]
}
}
}
}
]
}
```