Agent Skills › netalertx/NetAlertX › netalertx-plugin-run-development

netalertx-plugin-run-development

GitHub

指导如何创建、运行和测试NetAlertX插件。涵盖插件结构、配置、执行命令及日志处理，帮助开发者快速集成自定义功能。

.github/skills/plugin-run-development/SKILL.md netalertx/NetAlertX

Trigger Scenarios

创建插件运行插件测试插件插件开发

Install

npx skills add netalertx/NetAlertX --skill netalertx-plugin-run-development -g -y

More Options

Non-standard path

npx skills add https://github.com/netalertx/NetAlertX/tree/main/.github/skills/plugin-run-development -g -y

Use without installing

npx skills use netalertx/NetAlertX@netalertx-plugin-run-development

指定 Agent (Claude Code)

npx skills add netalertx/NetAlertX --skill netalertx-plugin-run-development -a claude-code -g -y

安装 repo 全部 skill

npx skills add netalertx/NetAlertX --all -g -y

预览 repo 内 skill

npx skills add netalertx/NetAlertX --list

SKILL.md

Frontmatter

{
    "name": "netalertx-plugin-run-development",
    "description": "Create and run NetAlertX plugins. Use this when asked to create plugin, run plugin, test plugin, plugin development, or execute plugin script."
}

Plugin Development

Expected Workflow for Running Plugins

Read this skill document for context and instructions.
Find the plugin in server/plugins/<code_name>/.
Read the plugin's config.json and script.py to understand its functionality and settings.
Formulate and run the command: python3 server/plugins/<code_name>/script.py.
Retrieve the result from the plugin log folder (/tmp/log/plugins/last_result.<PREF>.log) quickly, as the backend may delete it after processing.

Run a Plugin Manually

python3 server/plugins/<code_name>/script.py

Ensure sys.path includes /app/server/plugins and /app/server (as in the template).

Plugin Structure

server/plugins/<code_name>/
├── config.json      # Manifest with settings
├── script.py        # Main script
└── ...

Manifest Location

server/plugins/<code_name>/config.json

code_name == folder name
unique_prefix drives settings and filenames (e.g., ARPSCAN)

Settings Pattern

<PREF>_RUN: execution phase
<PREF>_RUN_SCHD: cron-like schedule
<PREF>_CMD: script path
<PREF>_RUN_TIMEOUT: timeout in seconds
<PREF>_WATCH: columns to watch for changes

Data Contract

Scripts write to /tmp/log/plugins/last_result.<PREF>.log

Important: The backend will almost immediately process this result file and delete it after ingestion. If you need to inspect the output, run the plugin and immediately retrieve the result file before the backend processes it.

Use server/plugins/plugin_helper.py:

from plugin_helper import Plugin_Objects

plugin_objects = Plugin_Objects()
plugin_objects.add_object(...)  # During processing
plugin_objects.write_result_file()  # Exactly once at end

Execution Phases

once: runs once at startup
schedule: runs on cron schedule
always_after_scan: runs after every scan
before_name_updates: runs before name resolution
on_new_device: runs when new device detected
on_notification: runs when notification triggered

Plugin Formats

Format	Purpose	Runs
publisher	Send notifications	`on_notification`
dev scanner	Create/manage devices	`schedule`
name discovery	Discover device names	`before_name_updates`
importer	Import from services	`schedule`
system	Core functionality	`schedule`