yocto-security-tools 1.0.0__tar.gz

yocto_security_tools-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026 Ericsson AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yocto_security_tools-1.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: yocto-security-tools
+Version: 1.0.0
+Summary: Standalone CVE management tools for Yocto/OpenEmbedded
+License: MIT
+Project-URL: Homepage, https://github.com/Ericsson/yocto-security-tools
+Project-URL: Repository, https://github.com/Ericsson/yocto-security-tools
+Project-URL: Issues, https://github.com/Ericsson/yocto-security-tools/issues
+Project-URL: Changelog, https://github.com/Ericsson/yocto-security-tools/blob/main/CHANGELOG.md
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.28
+Requires-Dist: packaging<27,>=23.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=7.0; extra == "dev"
+Requires-Dist: pytest-cov<8,>=4.0; extra == "dev"
+Requires-Dist: mypy<3,>=1.8; extra == "dev"
+Requires-Dist: ruff<1,>=0.4; extra == "dev"
+Dynamic: license-file

yocto_security_tools-1.0.0/README.md

@@ -0,0 +1,149 @@
+<!-- SPDX-License-Identifier: MIT -->
+# yocto-security-tools
+
+Standalone CVE management tools for Yocto/OpenEmbedded Linux distributions.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| **cve-metadata-extractor** | Find fix commits for CVEs from multiple public sources (Debian, OSV, CVEList V5, Ubuntu, NVD) |
+| **cve-corrector** | Automate backporting CVE fixes to Yocto recipes using devtool |
+| **cve-agent** | Orchestrate CVE backporting with AI-assisted conflict resolution |
+
+## Requirements
+
+- Python 3.9+
+- Git
+- For `cve-corrector` / `cve-agent`: a sourced Yocto build environment (`BBPATH` set)
+- For `cve-agent`: [kiro-cli](https://github.com/aws/kiro-cli) (or a custom AI backend plugin)
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### Find CVE fix metadata
+
+```bash
+# From Yocto cve-summary.json (output of sbom-cve-check)
+cve-metadata-extractor --yocto-summary cve-summary.json --output cve-metadata.json
+
+# For a specific CVE
+cve-metadata-extractor --cve-id CVE-2024-1234 --cve-component-name openssl
+```
+
+### Apply CVE patches
+
+```bash
+# Source your Yocto build environment first
+source oe-init-build-env
+
+# Apply a CVE fix
+cve-corrector --cve-id CVE-2024-1234 --cve-info cve-metadata.json
+
+# Resume after manual conflict resolution
+cve-corrector --continue
+```
+
+### AI-assisted backporting
+
+```bash
+# Requires kiro-cli (or another AI backend)
+cve-agent --cve-id CVE-2024-1234 --cve-info cve-metadata.json --trust
+
+# Batch mode
+cve-agent --cve-list cves.txt --cve-info cve-metadata.json --trust
+
+# Use a different AI backend
+cve-agent --cve-id CVE-2024-1234 --cve-info cve-metadata.json --backend my_backend
+```
+
+## How It Works
+
+```mermaid
+graph LR
+    E["cve-metadata-extractor<br/>Find fix commits"] -->|cve-metadata.json| C["cve-corrector<br/>Apply patches via devtool"]
+    C -->|exit code + state| A["cve-agent<br/>AI-assisted resolution"]
+    A -->|subprocess| C
+```
+
+Each tool works independently. Chain them via `--cve-info cve-metadata.json`.
+
+## Supported Input Formats
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| cve-summary.json | `--yocto-summary` | Output from Yocto's `sbom-cve-check` class |
+| Direct CVE ID | `--cve-id` | One or more CVE identifiers |
+| CVE list file | `--cve-list` | Text file with one CVE ID per line (agent only) |
+
+## Configuration
+
+The extractor reads configuration from `cve_metadata_extractor/config.json` by default.
+Override with the `CVE_EXTRACTOR_CONFIG` environment variable.
+
+### Storage (XDG Compliant)
+
+| Directory | Default | Override |
+|-----------|---------|----------|
+| Persistent data | `~/.local/share/yocto-security-tools/` | `CVE_TOOLS_DATA_DIR` |
+| Cache (expendable) | `~/.cache/yocto-security-tools/` | `CVE_TOOLS_CACHE_DIR` |
+
+### Config Keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `cvelistv5_url` | GitHub | Git URL to clone CVEList V5 from |
+| `debian_tracker_url` | salsa.debian.org | Git URL for Debian tracker |
+| `nvd_url` | GitHub | Git URL for NVD data |
+| `oe_branches` | `["scarthgap"]` | OE branches to check for fix status |
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `CVE_EXTRACTOR_CONFIG` | Override config.json path |
+| `CVE_TOOLS_DATA_DIR` | Override XDG data directory |
+| `CVE_TOOLS_CACHE_DIR` | Override XDG cache directory |
+| `GITHUB_TOKEN` | GitHub API access (required for PR metadata) |
+| `OPENEMBEDDED_TOKEN` | OE mailing list API |
+| `BBPATH` | Required for cve-corrector/cve-agent (Yocto build env) |
+| `CVE_EXTRA_SOURCES_DIR` | Override plugin directory for extractor |
+| `CVE_EXTRA_BACKENDS_DIR` | Override plugin directory for agent backends |
+
+## Plugin System
+
+Add custom CVE data sources or AI backends by dropping `.py` files in the `extra/` directory. See [extra/README.md](extra/README.md) for the plugin development guide.
+
+### Quick Example: Custom Source
+
+```python
+# extra/my_source.py
+from cve_metadata_extractor.sources import CveSource, SOURCE_REGISTRY
+
+class MySource(CveSource):
+    name = 'my_source'
+    def is_enabled(self, args): return True
+    def extract(self, cve_id, stats): return [], [], [], []
+
+SOURCE_REGISTRY.append(MySource())
+```
+
+## Development
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

yocto_security_tools-1.0.0/cve_agent/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,161 @@
+<!-- SPDX-License-Identifier: MIT -->
+# CVE Backport Agent Instructions
+
+## Scope Rules
+
+You may ONLY modify files listed in the **Allowed Files** section of the context header.
+A git pre-commit hook enforces this — commits with unauthorized files will be rejected.
+
+**NEVER do any of these:**
+- `git add .` or `git add -A`
+- `git commit --no-verify` or `git cherry-pick --no-verify`
+- Cherry-pick additional upstream commits beyond what cve_corrector already applied
+- Create or rename files not in the Allowed Files list
+- Modify `.gitignore` or any file not in the Allowed Files list
+- Run `cve_corrector.py` (the agent handles workflow progression)
+- Read files outside the workspace directory
+- Use the `glob` tool
+
+**Prerequisite commits**: If the upstream fix depends on a prior commit, do NOT
+cherry-pick it separately. Instead, manually adapt the conflicting code to work
+without the prerequisite — inline the necessary changes into the files already
+being modified. The generated patch must only contain the upstream fix commit's
+changes, adapted for the stable branch.
+
+**Files not in the baseline**: If the upstream commit adds a NEW file that is
+in the Allowed Files list, include it — `git cherry-pick` will stage it
+automatically. If it conflicts or requires infrastructure not present in the
+stable branch, mention it in the commit message as:
+`<file>: omitted (depends on <missing infrastructure>)`
+
+Only omit a file if including it would break the build or if it depends on
+code/headers/build rules that don't exist in the stable branch.
+
+## Workflow
+
+### 1. Analyse (always)
+```bash
+git log original-version..HEAD --oneline   # what was applied
+git show HEAD                               # understand the fix
+```
+If the patch is incompatible with the stable base, adapt it.
+
+If the CVE fix is **not applicable** to this version (e.g. the vulnerable code
+path, function, struct, or feature does not exist in the stable branch), do NOT
+make any code changes. Instead, write a conclusion file:
+
+```bash
+cat > "<agent_dir>/conclusion.json" <<'EOF'
+{"not_applicable": true, "reason": "<one-line explanation of why the CVE does not apply>"}
+EOF
+```
+
+Replace `<agent_dir>` with the actual agent dir path from the context header.
+The reason should be specific — mention the missing function, struct, code path,
+or feature and the version. Example:
+`"PBMAC1 infrastructure (PBMAC1PARAM, PBMAC1_get1_pbkdf2_param) does not exist in 3.2.6; CVE-2025-11187 is not applicable to this version"`
+
+After writing the conclusion file, **stop — do not make any other changes.**
+
+### 2. Resolve Conflicts (exit code 1)
+```bash
+git status && git diff                      # examine conflicts
+git show <upstream_sha>                     # upstream fix intent
+git log --oneline -20 -- <file>             # file history for context
+```
+Resolve conflicts, then:
+```bash
+git add <resolved_files>                    # ONLY allowed files
+```
+
+If you adapted the patch (not a verbatim cherry-pick), append your backport
+notes to `.git/MERGE_MSG` — **read the file first**, keep the original content,
+and append your notes after a blank line. Then:
+```bash
+git cherry-pick --no-edit --continue
+```
+
+### 3. Fix Build Errors (exit code 4)
+Read the last 50 lines of the build log. If the failing task belongs to a
+**different recipe** than the one being patched, **abort immediately** — do not
+attempt to fix it. This indicates a pre-existing or environmental issue.
+Otherwise, fix the code and amend the commit.
+
+### 4. Fix Test Failures (exit code 3)
+Fix the **backported code in the allowed files only**.
+If the fix requires changing a file not in the allowed list, stop and
+flag for human review. Document which tests failed and what code change
+fixed them in the commit message.
+
+### 5. Build Verification (mandatory after every change)
+```bash
+BUILD_LOG="<agent_dir>/build_$$.log"
+devtool build <recipe> > "$BUILD_LOG" 2>&1
+echo "Exit code: $?"
+```
+On failure: `tail -50 "$BUILD_LOG"`, fix, `git commit --amend --no-edit`, retry.
+If `devtool build` logs are insufficient, check Yocto task logs at:
+`<yocto_tmp>/work/<arch>/<recipe>/*/temp/log.do_compile`
+(paths are in the context header).
+On success: **stop — your work is done.**
+
+For cross-compilation: use `bitbake -c devshell <recipe>`, never run
+make/cmake/gcc directly.
+
+## Resolution Principles
+
+- **Minimal changes only** — smallest adaptation to make the fix work on stable
+- **Preserve upstream intent** — adapt APIs/signatures, never change fix logic
+- **Match surrounding whitespace** — use the same indentation style (tabs vs spaces, alignment width) as the surrounding code in the stable branch, not the upstream patch
+- **Check dependencies** — look for `Link:` in commit, prerequisite patches
+- **If uncertain, stop** — flag for human review rather than guess
+
+## Common Conflict Patterns
+
+| Pattern | Resolution | Commit Note |
+|---|---|---|
+| Function signature changed | Keep fix logic, adapt to stable signature | `Adapted foo_v2() to foo_v1() API` |
+| Struct member renamed | Use stable member name with upstream logic | `Member renamed netdev→ndev in original patch` |
+| Function moved to different file | Apply fix where function lives in stable | `Function in old_file.c in original patch` |
+| Missing helper function | Inline it or use stable equivalent | `Inlined helper_foo() (not in stable)` |
+
+## Commit Message Format
+
+**IMPORTANT: Preserve the original upstream commit message.** The `.git/MERGE_MSG`
+file contains the original upstream commit subject and body. You MUST keep it
+intact and only **append** your backport notes after it. Never replace or rewrite
+the original message.
+
+Only append notes if you adapted the patch. Use EXACTLY this markdown format — no
+alternative headers like "Conflict resolution notes:" or "Backport changes:".
+
+Append the following block after the original commit message (separated by a
+blank line):
+
+```
+Backport Resolution: <One or two sentences explaining what the upstream commit does — the functional
+change, not the conflict details.>
+
+Conflicts Resolved:
+
+<file> (<N> conflict[s]):
+- <What was changed and why, referencing stable vs upstream differences.>
+
+<file> (<N> conflict[s]):
+- <What was changed and why.>
+```
+
+Rules:
+- **Never delete or rewrite the original subject line or body** from `.git/MERGE_MSG`
+- Append your notes after the existing message, separated by a blank line
+- Start with a summary of the upstream fix's purpose (what it changes, why)
+- List ONLY files that had conflicts or required adaptation — skip clean files
+- For each file, state the conflict count and describe each adaptation
+- Mention specific function names, types, APIs, and why the stable branch differs
+- Omitted files: `<file>: omitted (not in branch)`
+- Do NOT add a "Changes from upstream" section (the agent generates that)
+- If you adapted the patch (not a verbatim cherry-pick), add a trailer line
+  after a blank line at the end of the commit message:
+  `Assisted-by: <backend>:<model>` where `<backend>` and `<model>` are the
+  **Backend** and **Model** values from the context header (e.g.
+  `Assisted-by: kiro:claude-sonnet-4-20250514`)

yocto_security_tools-1.0.0/cve_agent/__init__.py

@@ -0,0 +1,138 @@
+# Copyright (C) 2026 Ericsson AB
+# SPDX-License-Identifier: MIT
+"""CVE Agent - Orchestrates CVE backporting with AI-assisted conflict resolution.
+
+Wraps cve_corrector and spawns AI sessions to resolve conflicts, build errors,
+and test failures during CVE backporting.
+"""
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+# Exit codes (single source of truth: shared/exit_codes.py)
+from shared.exit_codes import (
+    EXIT_AGENT_ERROR,
+    EXIT_AI_TIMEOUT,
+    EXIT_ALREADY_APPLIED,
+    EXIT_BUILD_ERROR,
+    EXIT_BUILD_PREEXISTING,
+    EXIT_CHECKOUT_ERROR,
+    EXIT_CONFLICT,
+    EXIT_DEVTOOL_ERROR,
+    EXIT_GIT_ERROR,
+    EXIT_METADATA_ERROR,
+    EXIT_NOT_APPLICABLE,
+    EXIT_PATCH_ERROR,
+    EXIT_PTEST_ERROR,
+    EXIT_PTEST_PREEXISTING,
+    EXIT_SUCCESS,
+    EXIT_TRUST_DECLINED,
+)
+from shared.paths import data_dir
+
+# Exit codes that trigger the resolution loop (agent can attempt to fix)
+RECOVERABLE_EXITS = {EXIT_CONFLICT, EXIT_PTEST_ERROR, EXIT_BUILD_ERROR}
+
+# Exit codes that require immediate escalation (no point retrying)
+UNRECOVERABLE_EXITS = {EXIT_CHECKOUT_ERROR, EXIT_PATCH_ERROR,
+                       EXIT_METADATA_ERROR, EXIT_GIT_ERROR,
+                       EXIT_PTEST_PREEXISTING, EXIT_DEVTOOL_ERROR,
+                       EXIT_BUILD_PREEXISTING, EXIT_NOT_APPLICABLE}
+
+# Default paths
+DEFAULT_KNOWLEDGE_PATH = data_dir() / 'knowledge.json'
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_SESSION_TIMEOUT = 600
+CORRECTOR_CMD = [sys.executable, '-m', 'cve_corrector']
+AGENT_INSTRUCTIONS = Path(__file__).resolve().parent / 'AGENT_INSTRUCTIONS.md'
+
+
+class ResultStatus(Enum):
+    """Outcome status for a CVE processing attempt."""
+    SUCCESS = "success"
+    CONFLICT_RESOLVED = "conflict_resolved"
+    FAILED = "failed"
+    ESCALATED = "escalated"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for a single CVE agent run."""
+    cve_id: str
+    cve_info_path: Optional[Path] = None
+    trust_mode: bool = False
+    max_retries: int = DEFAULT_MAX_RETRIES
+    max_total_attempts: int = 0  # 0 = no cap beyond per-step max_retries
+    mirror_dir: Optional[Path] = None
+    meta_layer: Optional[Path] = None
+    skip_ptest: bool = False
+    clean: bool = False
+    model: str = "claude-sonnet-4.6"
+    session_timeout: int = DEFAULT_SESSION_TIMEOUT
+    interactive: bool = False
+    bbappend: bool = False
+    skip_cve_applicability: bool = False
+    fix_url: Optional[str] = None
+    recipe: Optional[str] = None
+    backend: str = "kiro"
+
+
+@dataclass
+class CveResult:
+    """Outcome of processing a single CVE."""
+    cve_id: str
+    status: ResultStatus
+    retries: int = 0
+    duration: float = 0.0
+    resolution_summary: str = ""
+
+
+def get_build_dir(workspace_path: Path) -> Path:
+    """Derive the Yocto build directory from a devtool workspace path.
+
+    The devtool workspace structure is: <build>/workspace/sources/<recipe>,
+    so the build directory is three levels up from the workspace path.
+
+    Args:
+        workspace_path: Path to the devtool workspace source directory.
+
+    Returns:
+        Path to the Yocto build directory.
+    """
+    return workspace_path.parent.parent.parent
+
+
+def get_agent_dir(workspace_path: Path) -> Path:
+    """Get or create the agent working directory outside the git workspace.
+
+    Uses the build workspace's cve_agent/ directory to avoid polluting
+    the source git repo with agent artifacts.
+
+    Args:
+        workspace_path: Path to the devtool workspace source directory.
+
+    Returns:
+        Path to the cve_agent/<recipe> directory, created if needed.
+    """
+    recipe = workspace_path.name
+    build_workspace = workspace_path.parent.parent
+    agent_dir = build_workspace / 'cve_agent' / recipe
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    return agent_dir
+
+
+__all__ = [
+    'AgentConfig', 'CveResult', 'ResultStatus',
+    'RECOVERABLE_EXITS', 'UNRECOVERABLE_EXITS',
+    'DEFAULT_KNOWLEDGE_PATH', 'DEFAULT_MAX_RETRIES', 'DEFAULT_SESSION_TIMEOUT',
+    'CORRECTOR_CMD', 'AGENT_INSTRUCTIONS',
+    'get_build_dir', 'get_agent_dir',
+    'EXIT_SUCCESS', 'EXIT_CONFLICT', 'EXIT_CHECKOUT_ERROR', 'EXIT_PTEST_ERROR',
+    'EXIT_BUILD_ERROR', 'EXIT_PATCH_ERROR', 'EXIT_METADATA_ERROR', 'EXIT_GIT_ERROR',
+    'EXIT_PTEST_PREEXISTING', 'EXIT_DEVTOOL_ERROR', 'EXIT_BUILD_PREEXISTING',
+    'EXIT_ALREADY_APPLIED', 'EXIT_NOT_APPLICABLE',
+    'EXIT_TRUST_DECLINED', 'EXIT_AGENT_ERROR', 'EXIT_AI_TIMEOUT',
+]