Security Guidelines

Best practices for creating secure skills and understanding the security scanner.

Security Scanner

All skills are automatically scanned before publishing. The scanner checks for:

Hardcoded secrets, API keys, and credentials
Dangerous shell commands and code execution patterns
Suspicious network requests and data exfiltration
File system operations outside declared capabilities
Known vulnerability patterns

Security Score

Skills receive a score from 0-100:

80-100: Excellent

Minimal security concerns

50-79: Fair

Some issues to review

0-49: Rejected

Cannot be published

What to Avoid

Hardcoded Secrets

Never include API keys, passwords, or tokens in your skill.

Bad: API_KEY = "sk-abc123..."

Dangerous Commands

Avoid destructive shell commands.

Bad: rm -rf /, chmod 777, sudo

Arbitrary Code Execution

Don't use eval() or similar dynamic execution.

Bad: eval(user_input), exec(), Function()

Undeclared Capabilities

Don't access files or network without declaring capabilities.

Bad: Reading /etc/passwd, ~/.ssh/

Best Practices

Declare All Capabilities

Be explicit about what permissions your skill needs.

capabilities:
  - capability: file:read
    reason: To read config files
    constraints:
      paths: ["*.json", "*.yaml"]

Use Minimal Permissions

Only request capabilities you actually need. Users are more likely to trust skills with fewer permission requirements.

Constrain Access

Use constraints to limit file paths, network hosts, and other access patterns to the minimum required.

Validate Inputs

Always validate and sanitize user-provided inputs before using them in commands or file paths.

Capability Guidelines

file:read / file:write

Always specify path constraints. Never request access to sensitive directories.

Use specific patterns: *.pdf, ./data/*
Avoid broad patterns like *
Never access ~/.ssh/, ~/.aws/, /etc/

network:https

Specify which hosts your skill needs to contact.

List specific domains in constraints
Explain why network access is needed
Don't make requests to user-controlled URLs

shell:execute

This capability receives extra scrutiny. Use sparingly.

Only use for well-known, safe commands
Never construct commands from user input
Consider if there's an alternative approach

Registry Security

The Asterism registry includes multiple protections against supply chain attacks.

Typosquatting Protection

When publishing a skill, names are checked against existing popular skills to prevent confusingly similar names:

Levenshtein distance analysis for similarity detection
Lookalike character detection (0→o, 1→i, 5→s)
Pattern matching for common typo variations

Blocked: "reviewing-c0de" (too similar to "reviewing-code")

Reserved Names

Certain words are reserved to prevent impersonation:

AI Companies:

anthropic, claude
openai, chatgpt
google, gemini
microsoft, copilot

Platform:

admin, system
official, verified
askskills, agentskills

Security:

root, sudo
shell

Skill Deprecation

Skills with security issues can be marked as deprecated with warnings shown to users. Deprecated skills include a message explaining the issue and a link to a recommended replacement when available.

Common Scanner Issues

False Positives

Sometimes the scanner flags patterns that look suspicious but are actually safe. If you believe you've received a false positive, you can add comments explaining the context, or contact us for review.

Example URLs

Use example.com for documentation URLs. Don't include real API endpoints in examples that might be mistaken for hardcoded credentials.

Test Credentials

Use obvious placeholder values like "YOUR_API_KEY_HERE" instead of realistic-looking fake keys that might trigger the scanner.

Skill Protection

The platform includes multiple protections to prevent skill copying and plagiarism.

Similarity Detection

When publishing, content is compared against existing skills using TF-IDF and Jaccard similarity algorithms. Skills with 80%+ similarity to existing skills are blocked.

0-50% similarity: Passes without warnings
50-80% similarity: Warning, requires acknowledgment
80-100% similarity: Blocked, must use fork feature

Content Fingerprinting

Downloads include invisible watermarks using zero-width Unicode characters. If content is leaked, fingerprints can trace it back to the original downloader.

Premium Hosted Execution

Premium skills can be configured for hosted-only execution where the content never leaves the server. Users execute skills via API without accessing the source.

Author Reputation

Authors have reputation scores based on trust, quality, and helpfulness. Verified publishers receive badges and higher visibility. Copy reports and DMCA takedowns negatively impact reputation.

DMCA Process

We support the DMCA takedown process for copyright infringement. See our DMCA page for details on submitting takedown requests or counter-notices.

Reporting Security Issues

If you discover a security vulnerability in a skill:

Email security@joinasterism.com with details
Include the skill name and specific concerns
We'll investigate and take appropriate action

For vulnerabilities in the Asterism platform itself, please follow responsible disclosure practices.