gnezim/clawsec

Fork 0

mirror of https://github.com/prompt-security/clawsec.git synced 2026-06-13 05:28:02 +03:00

Files

T

David Abutbul d3c703aea6 ClawSec init

2026-02-05 21:58:23 +02:00

15 KiB

Raw Blame History

Contributing to ClawSec Skills

Thank you for your interest in contributing security skills to the ClawSec ecosystem! This guide will walk you through creating, testing, and submitting new skills.

Getting Started
Skill Structure
Creating a New Skill
skill.json Reference
Testing Your Skill
Submission Process
Review Criteria
After Acceptance
Submitting Security Advisories

Getting Started

1. Fork the Repository

Navigate to the ClawSec repository
Click the "Fork" button in the top-right corner
Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/clawsec.git
cd clawsec

2. Set Up Your Environment

# Add upstream remote to sync with main repo
git remote add upstream https://github.com/prompt-security/clawsec.git

# Install dependencies (if any)
npm install

# Create a new branch for your skill
git checkout -b skill/my-new-skill

Trust & Verification Model

All skills distributed through ClawSec undergo security review and are hashed for agent verification. Trust is implicit:

Backend Verification: Every skill is validated against checksums, SBOM manifests, and security policies
Transparent Security: SHA256 checksums, signature verification, and advisory feeds operate automatically
Contribution Flow: Submit skills via PR → maintainer review → approval → release

Skill Structure

Each skill lives in its own directory under skills/. Here's the standard structure:

skills/
  └── my-skill-name/
      ├── skill.json          # Required: Metadata and SBOM
      ├── SKILL.md            # Required: Main skill documentation
      ├── README.md           # Optional: Additional documentation
      └── scripts/
          ├── # Any supporting scripts your skill needs

Example: Minimal Skill

skills/
  └── my-security-scanner/
      ├── skill.json
      └── SKILL.md

Example: Complex Skill

skills/
  └── advanced-analyzer/
      ├── skill.json
      ├── SKILL.md
      ├── README.md
      ├── templates/
      │   └── report-template.md
      ├── scripts/
      │   └── action.py
      └── config/
          └── rules.json

Creating a New Skill

Step 1: Create Skill Directory

mkdir -p skills/my-skill-name
cd skills/my-skill-name

Step 2: Create skill.json

Create skill.json with the following structure:

{
  "name": "my-skill-name",
  "version": "0.0.1",
  "description": "Brief description of what your skill does",
  "author": "your-github-username",
  "license": "MIT",
  "homepage": "https://github.com/prompt-security/clawsec",
  "keywords": ["security", "relevant", "tags"],

  "sbom": {
    "files": [
      {
        "path": "SKILL.md",
        "required": true,
        "description": "Main skill documentation"
      }
    ]
  },

  "openclaw": {
    "emoji": "🔒",
    "category": "security",
    "requires": {
      "bins": ["curl", "jq"]
    },
    "triggers": [
      "keyword that activates skill",
      "another trigger phrase",
      "security check"
    ]
  }
}

Important Notes:

Start with version 0.0.1
List ALL files your skill needs in the SBOM

Step 3: Create SKILL.md

This is the main documentation for your skill. Use this template:

# My Skill Name

## Overview

Brief description of what this skill does and why it's useful for AI agent security.

## Usage

How to use the skill:

```bash
# Example commands or usage patterns

Features

Feature 1: Description
Feature 2: Description
Feature 3: Description

Requirements

Required tools: curl, jq, etc.
Any system dependencies
Prerequisites

Security Considerations

Important security notes about this skill.

Examples

Example 1: Basic Usage

Description and example output.

Example 2: Advanced Usage

Description and example output.

Troubleshooting

Common issues and solutions.

Contributing

How others can improve this skill.


### Step 4: Add Supporting Files

Add any additional files your skill needs (configs, templates, scripts), and **ensure they're listed in skill.json's SBOM**.

---

## skill.json Reference

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Skill identifier (lowercase, hyphens only) |
| `version` | string | Semantic version (0.0.1) |
| `description` | string | Brief description (max 200 chars) |
| `author` | string | Your GitHub username or organization |
| `license` | string | License type (prefer MIT) |
| `homepage` | string | Repository URL |
| `keywords` | array | Searchable tags |
| `sbom` | object | Software Bill of Materials |

### Verification

All skills published through ClawSec are reviewed by Prompt Security staff or designated maintainers before release:

- All published skills undergo security review
- Checksums and SBOM validation ensure integrity
- There is no distinction between "verified" and "community" skills - every skill in the catalog has passed review

### SBOM Structure

The SBOM (Software Bill of Materials) lists all files that are part of your skill:

```json
{
  "sbom": {
    "files": [
      {
        "path": "SKILL.md",
        "required": true,
        "description": "Main skill file"
      },
      {
        "path": "config/rules.json",
        "required": false,
        "description": "Optional configuration rules"
      }
    ]
  }
}

Critical: Every file your skill uses MUST be listed in the SBOM. This enables:

Automated checksum generation
Integrity verification
Secure distribution

OpenClaw Integration

The openclaw section defines how the skill integrates with Claude Code:

{
  "openclaw": {
    "emoji": "🔒",
    "category": "security",
    "requires": {
      "bins": ["curl", "jq", "git"]
    },
    "triggers": [
      "keyword to activate skill",
      "another trigger phrase"
    ]
  }
}

Categories: security, monitoring, analysis, reporting, utility

Testing Your Skill

1. Validate JSON Structure

# Validate skill.json is valid JSON
cat skills/my-skill-name/skill.json | jq .

2. Verify SBOM Completeness

# Check all SBOM files exist
cd skills/my-skill-name
for file in $(jq -r '.sbom.files[].path' skill.json); do
  [ -f "$file" ] && echo "✓ $file" || echo "✗ $file MISSING"
done

3. Test Locally (if applicable)

If your skill includes executable scripts or requires testing:

# Follow the testing instructions in your SKILL.md

4. Check for Common Issues

All SBOM files exist
skill.json is valid JSON
Version is 1.0.0 for new skills
No hardcoded credentials or secrets
Trigger phrases are descriptive
Required binaries are documented

Submission Process

1. Commit Your Changes

# From the repository root
git add skills/my-skill-name/
git commit -m "feat(skills): add my-skill-name security skill"

Commit Message Format:

feat(skills): add <skill-name> <brief description>

- Key feature 1
- Key feature 2
- Security benefit

2. Push to Your Fork

git push origin skill/my-new-skill

3. Create a Pull Request

Go to your fork on GitHub
Click "Pull Request"
Select your branch (skill/my-new-skill)
Fill out the PR template:

## Skill Contribution: [Skill Name]

### Description
Brief overview of what this skill does.

### Security Benefits
How this skill improves AI agent security.

### Testing Performed
- [ ] JSON validation passed
- [ ] SBOM files verified
- [ ] Local testing completed
- [ ] No secrets or credentials included

### Checklist
- [ ] skill.json is complete
- [ ] SKILL.md documentation is clear
- [ ] All SBOM files are present
- [ ] Version is 0.0.1 (if new skill)

### Additional Notes
Any special considerations for reviewers.

Review Criteria

Maintainers will review your skill based on:

Security

No malicious code or backdoors
No hardcoded credentials
Safe command execution (no command injection)
Proper input validation
No unnecessary privileges required

Quality

Clear documentation
Well-structured code
Follows naming conventions
Complete SBOM
Descriptive trigger phrases

Value

Provides clear security benefit
Not duplicate of existing skill
Useful for AI agent protection
Aligns with ClawSec mission

Technical

Valid JSON structure
All SBOM files present
Correct versioning
Proper metadata

After Acceptance

Once your skill is accepted:

Maintainers will:
- Review your PR (Prompt Security staff or designated maintainers)
- Merge your PR after security review
- Create the first release using scripts/release-skill.sh
- Generate checksums and publish to GitHub Releases
- Update the skills catalog website
You'll be credited:
- Listed as the skill author
- Mentioned in release notes
- Added to contributors list
Future updates:
- Submit PRs with version bumps for improvements
- Maintainers will handle releases
- Follow semantic versioning:
  - 1.0.1 - Patch (bug fixes)
  - 1.1.0 - Minor (new features)
  - 2.0.0 - Major (breaking changes)

Questions?

Issues: GitHub Issues
Discussions: GitHub Discussions
Security: For security-sensitive contributions, email security@prompt.security

Example Contribution

Here's a complete example of a minimal skill contribution:

# Fork and clone
git clone https://github.com/YOUR-USERNAME/clawsec.git
cd clawsec

# Create branch
git checkout -b skill/simple-scanner

# Create skill
mkdir -p skills/simple-scanner
cat > skills/simple-scanner/skill.json << 'EOF'
{
  "name": "simple-scanner",
  "version": "0.0.1,
  "description": "Basic security scanner for AI agents",
  "author": "contributor-name",
  "license": "MIT",
  "homepage": "https://github.com/prompt-security/clawsec",
  "keywords": ["security", "scanner", "basic"],
  "sbom": {
    "files": [
      { "path": "SKILL.md", "required": true, "description": "Scanner documentation" }
    ]
  },
  "openclaw": {
    "emoji": "🔍",
    "category": "security",
    "requires": { "bins": ["curl"] },
    "triggers": ["simple scan", "basic security check"]
  }
}
EOF

cat > skills/simple-scanner/SKILL.md << 'EOF'
# Simple Scanner

A basic security scanner for AI agents.

## Usage
Run a simple security scan on your agent configuration.

## Features
- Quick security checks
- Minimal dependencies
- Easy to use
EOF

# Validate
cat skills/simple-scanner/skill.json | jq .

# Commit and push
git add skills/simple-scanner/
git commit -m "feat(skills): add simple-scanner security skill

- Provides basic security scanning
- Minimal dependencies
- Easy to use for beginners"
git push origin skill/simple-scanner

Then create a pull request on GitHub!

Submitting Security Advisories

Found a prompt injection vector, malicious skill, or security vulnerability affecting AI agents? Help protect the community by submitting a security advisory.

Advisory Types

Type	Description	Example
`prompt_injection`	Detected prompt injection or social engineering	Skill contains hidden instructions to exfiltrate data
`vulnerable_skill`	Skill with security vulnerabilities	Skill executes unsanitized user input
`tampering_attempt`	Attempt to disable/modify security controls	Instructions to remove ClawSec or ignore security checks

How to Submit

1. Open a Security Incident Report

Go to Issues → New Issue
Select "Security Incident Report" template
Fill out all required sections:

Required Fields:

Opener Type - Are you a human or an AI agent reporting this?
Report Type - What kind of issue is this?
Severity - How severe is the threat?
Title - Brief descriptive title
Description - Detailed explanation of the vulnerability
Affected - Which skill(s) and version(s) are affected
Recommended Action - What should users do?

Optional but Helpful:

Evidence (sanitized payloads, indicators)
Reporter information (for follow-up questions)

2. Privacy Checklist

Before submitting, ensure you have:

Removed all real user data and PII
Not included any API keys, credentials, or secrets
Sanitized evidence to describe issues abstractly
No proprietary or confidential information included

3. Wait for Review

A maintainer will:

Review your report for validity and completeness
Assess the severity and impact
Add the advisory-approved label when ready to publish

4. Automatic Publication

Once approved, the community-advisory workflow automatically:

Parses your issue content
Generates an advisory ID: CLAW-{YEAR}-{ISSUE_NUMBER} (e.g., CLAW-2026-0042)
Adds the advisory to advisories/feed.json
Comments on your issue confirming publication

Advisory ID Format

Source	Format	Example
NVD CVE	`CVE-YYYY-NNNNN`	`CVE-2026-24763`
Community Report	`CLAW-YYYY-NNNN`	`CLAW-2026-0042`

The NNNN in community advisories is your GitHub issue number, zero-padded to 4 digits.

Example Security Report

## Opener Type
- [x] Agent (automated report)

## Report Type
- [x] Vulnerable Skill - Found a skill with security issues

## Severity
- [x] High - Significant security risk, potential for harm

## Title
Data exfiltration via helper-plus skill network calls

## Description
The helper-plus skill was observed sending conversation data to an external
server (suspicious-domain.com) on every invocation. The skill makes
undocumented network calls that transmit full conversation context to a
domain not mentioned in the skill description.

## Affected

### Skill Name
helper-plus

### Skill Version
0.0.1, 1.0.0, 1.0.1

## Recommended Action
Remove helper-plus immediately. Do not use versions 0.0.1, 1.0.0 or 1.0.1.
Wait for a verified patched version.

## Reporter Information (Optional)
**Agent/User Name:** SecurityBot

After Publication

Once your advisory is published:

Agents receive it - The feed is served from raw GitHub, so agents see it on their next feed check
You're credited - Your issue is linked in the advisory
Community is protected - Agents using ClawSec Feed will be alerted

Questions?

General questions: GitHub Discussions
Sensitive reports: Email security@prompt.security for issues too sensitive for public disclosure

Thank you for contributing to ClawSec security! 🛡️

15 KiB Raw Blame History

Contributing to ClawSec Skills

Table of Contents

Getting Started

1. Fork the Repository

2. Set Up Your Environment

Trust & Verification Model

Skill Structure

Example: Minimal Skill

Example: Complex Skill

Creating a New Skill

Step 1: Create Skill Directory

Step 2: Create skill.json

Step 3: Create SKILL.md

Features

Requirements

Security Considerations

Examples

Example 1: Basic Usage

Example 2: Advanced Usage

Troubleshooting

Contributing

OpenClaw Integration

Testing Your Skill

1. Validate JSON Structure

2. Verify SBOM Completeness

3. Test Locally (if applicable)

4. Check for Common Issues

Submission Process

1. Commit Your Changes

2. Push to Your Fork

3. Create a Pull Request

Review Criteria

Security

Quality

Value

Technical

After Acceptance

Questions?

Example Contribution

Submitting Security Advisories

Advisory Types

How to Submit

1. Open a Security Incident Report

2. Privacy Checklist

3. Wait for Review

4. Automatic Publication

Advisory ID Format

Example Security Report

After Publication

Questions?

15 KiB

Raw Blame History