add capa-diff for comparing capability deltas between result docs#2959
add capa-diff for comparing capability deltas between result docs#2959akshat4703 wants to merge 2 commits intomandiant:masterfrom
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning to the master (unreleased) section of CHANGELOG.md. If no CHANGELOG update is needed add the following to the PR description: [x] No CHANGELOG update needed
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
github-actions
bot
dismissed
their stale review
CHANGELOG updated or no update needed, thanks! 😄
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new script, capa-diff.py, for comparing capabilities between two capa JSON result documents. The script is well-structured and includes support for both text and JSON output formats. A smoke test has also been added to ensure the script's basic functionality is covered in CI. My review includes a suggestion to improve type safety and readability in the new script by using a TypedDict.
| from __future__ import annotations | ||
|
|
||
| import json | ||
| import sys | ||
| import argparse | ||
| from pathlib import Path | ||
|
|
||
| import capa.render.utils as rutils | ||
| import capa.render.default as rdefault | ||
| import capa.render.result_document as rd | ||
|
|
||
|
|
||
| def _parse_args(argv: list[str]) -> argparse.Namespace: | ||
| parser = argparse.ArgumentParser(description="Compare capabilities in two capa JSON result documents.") | ||
| parser.add_argument("old", type=Path, help="path to older/baseline capa JSON result document") | ||
| parser.add_argument("new", type=Path, help="path to newer/target capa JSON result document") | ||
| parser.add_argument( | ||
| "--format", | ||
| dest="output_format", | ||
| choices=("text", "json"), | ||
| default="text", | ||
| help="render output as text or json (default: text)", | ||
| ) | ||
| parser.add_argument( | ||
| "--include-subscope-rules", | ||
| action="store_true", | ||
| help="include rules that only matched as subrule references", | ||
| ) | ||
| return parser.parse_args(argv) | ||
|
|
||
|
|
||
| def _load_result_document(path: Path) -> rd.ResultDocument: | ||
| return rd.ResultDocument.model_validate_json(path.read_text(encoding="utf-8")) | ||
|
|
||
|
|
||
| def _collect_capabilities(doc: rd.ResultDocument, include_subscope_rules: bool = False) -> dict[str, dict[str, object]]: | ||
| hidden = set() | ||
| if not include_subscope_rules: | ||
| hidden = rdefault.find_subrule_matches(doc) | ||
|
|
||
| capabilities: dict[str, dict[str, object]] = {} | ||
| for rule in rutils.capability_rules(doc): | ||
| if rule.meta.name in hidden: | ||
| continue | ||
|
|
||
| capabilities[rule.meta.name] = { | ||
| "name": rule.meta.name, | ||
| "namespace": rule.meta.namespace, | ||
| "match_count": len(rule.matches), | ||
| } | ||
| return capabilities | ||
|
|
||
|
|
||
| def _render_text(added: list[dict[str, object]], removed: list[dict[str, object]]) -> str: |
There was a problem hiding this comment.
For better type safety and code clarity, consider using a TypedDict for the structure of a capability. This makes the code easier to understand and maintain, as it explicitly defines the shape of the dictionary. This also allows for more precise type hints in function signatures.
from __future__ import annotations
import json
import sys
import argparse
from pathlib import Path
from typing import TypedDict
import capa.render.utils as rutils
import capa.render.default as rdefault
import capa.render.result_document as rd
class CapabilityInfo(TypedDict):
name: str
namespace: str | None
match_count: int
def _parse_args(argv: list[str]) -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Compare capabilities in two capa JSON result documents.")
parser.add_argument("old", type=Path, help="path to older/baseline capa JSON result document")
parser.add_argument("new", type=Path, help="path to newer/target capa JSON result document")
parser.add_argument(
"--format",
dest="output_format",
choices=("text", "json"),
default="text",
help="render output as text or json (default: text)",
)
parser.add_argument(
"--include-subscope-rules",
action="store_true",
help="include rules that only matched as subrule references",
)
return parser.parse_args(argv)
def _load_result_document(path: Path) -> rd.ResultDocument:
return rd.ResultDocument.model_validate_json(path.read_text(encoding="utf-8"))
def _collect_capabilities(doc: rd.ResultDocument, include_subscope_rules: bool = False) -> dict[str, CapabilityInfo]:
hidden = set()
if not include_subscope_rules:
hidden = rdefault.find_subrule_matches(doc)
capabilities: dict[str, CapabilityInfo] = {}
for rule in rutils.capability_rules(doc):
if rule.meta.name in hidden:
continue
capabilities[rule.meta.name] = {
"name": rule.meta.name,
"namespace": rule.meta.namespace,
"match_count": len(rule.matches),
}
return capabilities
def _render_text(added: list[CapabilityInfo], removed: list[CapabilityInfo]) -> str:1 participant
This PR adds a standalone helper script, scripts/capa-diff.py, to compare two capa JSON result documents and report added/removed capabilities. It defaults to text output and also supports --format json; it can optionally include subscope-only matches via --include-subscope-rules.
Also added a script smoke test entry in tests/test_scripts.py to ensure the helper runs in CI script coverage.