@vulcn/plugin-payloads 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/dist/index.cjs +76 -339
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +59 -50
  4. package/dist/index.d.ts +59 -50
  5. package/dist/index.js +70 -337
  6. package/dist/index.js.map +1 -1
  7. package/package.json +3 -3
package/dist/index.d.cts CHANGED
@@ -2,36 +2,60 @@ import { z } from 'zod';
2
2
  import { RuntimePayload, VulcnPlugin } from '@vulcn/engine';
3
3
 
4
4
  /**
5
- * Built-in security payloads
6
- * Curated, tested, fast defaults for common vulnerability categories
5
+ * PayloadBox Loader
6
+ *
7
+ * Fetches payloads from PayloadsAllTheThings GitHub repository.
8
+ * This is the primary payload source for Vulcn — community-curated,
9
+ * battle-tested payloads from the largest security payload collection.
10
+ *
11
+ * Supports short aliases for convenience:
12
+ * xss, sqli, xxe, cmd, redirect, traversal
7
13
  */
8
14
 
9
15
  /**
10
- * Built-in payloads - curated, tested, fast defaults
16
+ * Canonical PayloadBox type names (as they appear in PayloadsAllTheThings)
11
17
  */
12
- declare const BUILTIN_PAYLOADS: Record<string, RuntimePayload>;
13
-
18
+ type PayloadBoxType = "xss" | "sql-injection" | "xxe" | "command-injection" | "open-redirect" | "path-traversal";
14
19
  /**
15
- * PayloadBox Loader
16
- * Fetches payloads from PayloadsAllTheThings GitHub repository
20
+ * Get all available payload type names (canonical)
17
21
  */
18
-
22
+ declare function getPayloadBoxTypes(): PayloadBoxType[];
19
23
  /**
20
- * Supported PayloadBox types
24
+ * Get all short aliases
21
25
  */
22
- type PayloadBoxType = "xss" | "sql-injection" | "xxe" | "command-injection" | "open-redirect" | "path-traversal";
26
+ declare function getAliases(): Record<string, PayloadBoxType>;
23
27
  /**
24
- * Get available PayloadBox types
28
+ * Resolve a user-provided name to a canonical PayloadBox type.
29
+ *
30
+ * Accepts:
31
+ * "xss" → "xss"
32
+ * "sqli" → "sql-injection"
33
+ * "sql-injection" → "sql-injection"
34
+ * "cmd" → "command-injection"
35
+ *
36
+ * Returns null if the name doesn't match any known type.
25
37
  */
26
- declare function getPayloadBoxTypes(): PayloadBoxType[];
38
+ declare function resolvePayloadType(name: string): PayloadBoxType | null;
27
39
  /**
28
- * Load payloads from PayloadBox
40
+ * Check if a name resolves to a valid PayloadBox type
41
+ */
42
+ declare function isValidPayloadName(name: string): boolean;
43
+ /**
44
+ * Get description for a payload type
45
+ */
46
+ declare function getDescription(type: PayloadBoxType): string;
47
+ /**
48
+ * Load payloads from PayloadBox.
29
49
  *
30
- * @param type - PayloadBox type (xss, sql-injection, etc.)
31
- * @param limit - Maximum number of payloads to include
32
- * @param fetchFn - Fetch function to use (for testing/DI)
50
+ * Accepts both canonical names and short aliases:
51
+ * loadPayloadBox("xss") → fetches XSS payloads
52
+ * loadPayloadBox("sqli") → fetches SQL injection payloads
33
53
  */
34
- declare function loadPayloadBox(type: string, limit?: number, fetchFn?: typeof fetch): Promise<RuntimePayload>;
54
+ declare function loadPayloadBox(name: string, limit?: number, fetchFn?: typeof fetch): Promise<RuntimePayload>;
55
+ /**
56
+ * Clear PayloadBox cache
57
+ */
58
+ declare function clearPayloadBoxCache(): void;
35
59
 
36
60
  /**
37
61
  * File Loader
@@ -51,10 +75,12 @@ declare function loadFromFile(filePath: string): Promise<RuntimePayload[]>;
51
75
  * @vulcn/plugin-payloads
52
76
  * Official payload loader plugin for Vulcn
53
77
  *
54
- * Provides:
55
- * - Built-in payloads (XSS, SQLi, SSRF, XXE, etc.)
56
- * - PayloadBox loader (PayloadsAllTheThings)
57
- * - Custom file loader (YAML/JSON)
78
+ * Payload sources (in order of priority):
79
+ * 1. PayloadBox — community-curated payloads from PayloadsAllTheThings (default)
80
+ * 2. Custom files — expert-provided YAML/JSON payload files
81
+ *
82
+ * Short aliases for payload types:
83
+ * xss, sqli, xxe, cmd, redirect, traversal
58
84
  */
59
85
 
60
86
  /**
@@ -62,49 +88,32 @@ declare function loadFromFile(filePath: string): Promise<RuntimePayload[]>;
62
88
  */
63
89
  declare const configSchema: z.ZodObject<{
64
90
  /**
65
- * Include built-in payloads (default: true)
66
- */
67
- builtin: z.ZodDefault<z.ZodBoolean>;
68
- /**
69
- * Specific built-in payload names to include (if not all)
70
- */
71
- include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
72
- /**
73
- * Built-in payload names to exclude
74
- */
75
- exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
76
- /**
77
- * PayloadBox types to fetch from PayloadsAllTheThings
78
- * e.g., ["xss", "sql-injection", "xxe"]
91
+ * Payload types to load from PayloadsAllTheThings.
92
+ * Accepts short aliases: xss, sqli, xxe, cmd, redirect, traversal
93
+ * @example ["xss", "sqli"]
79
94
  */
80
- payloadbox: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
95
+ types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
81
96
  /**
82
- * Limit per PayloadBox type
97
+ * Maximum payloads per type (default 50)
83
98
  */
84
- payloadboxLimit: z.ZodDefault<z.ZodNumber>;
99
+ limit: z.ZodDefault<z.ZodNumber>;
85
100
  /**
86
101
  * Custom payload files to load (YAML/JSON)
87
102
  */
88
103
  files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
89
104
  }, "strip", z.ZodTypeAny, {
90
- builtin: boolean;
91
- payloadboxLimit: number;
92
- include?: string[] | undefined;
93
- exclude?: string[] | undefined;
94
- payloadbox?: string[] | undefined;
105
+ limit: number;
106
+ types?: string[] | undefined;
95
107
  files?: string[] | undefined;
96
108
  }, {
97
- builtin?: boolean | undefined;
98
- include?: string[] | undefined;
99
- exclude?: string[] | undefined;
100
- payloadbox?: string[] | undefined;
101
- payloadboxLimit?: number | undefined;
109
+ types?: string[] | undefined;
110
+ limit?: number | undefined;
102
111
  files?: string[] | undefined;
103
112
  }>;
104
113
  type PayloadsPluginConfig = z.infer<typeof configSchema>;
105
114
  /**
106
- * Payloads Plugin - loads payloads from various sources
115
+ * Payloads Plugin
107
116
  */
108
117
  declare const plugin: VulcnPlugin;
109
118
 
110
- export { BUILTIN_PAYLOADS, type PayloadsPluginConfig, plugin as default, getPayloadBoxTypes, loadFromFile, loadFromFiles, loadPayloadBox };
119
+ export { type PayloadsPluginConfig, clearPayloadBoxCache, plugin as default, getAliases, getDescription, getPayloadBoxTypes, isValidPayloadName, loadFromFile, loadFromFiles, loadPayloadBox, resolvePayloadType };
package/dist/index.d.ts CHANGED
@@ -2,36 +2,60 @@ import { z } from 'zod';
2
2
  import { RuntimePayload, VulcnPlugin } from '@vulcn/engine';
3
3
 
4
4
  /**
5
- * Built-in security payloads
6
- * Curated, tested, fast defaults for common vulnerability categories
5
+ * PayloadBox Loader
6
+ *
7
+ * Fetches payloads from PayloadsAllTheThings GitHub repository.
8
+ * This is the primary payload source for Vulcn — community-curated,
9
+ * battle-tested payloads from the largest security payload collection.
10
+ *
11
+ * Supports short aliases for convenience:
12
+ * xss, sqli, xxe, cmd, redirect, traversal
7
13
  */
8
14
 
9
15
  /**
10
- * Built-in payloads - curated, tested, fast defaults
16
+ * Canonical PayloadBox type names (as they appear in PayloadsAllTheThings)
11
17
  */
12
- declare const BUILTIN_PAYLOADS: Record<string, RuntimePayload>;
13
-
18
+ type PayloadBoxType = "xss" | "sql-injection" | "xxe" | "command-injection" | "open-redirect" | "path-traversal";
14
19
  /**
15
- * PayloadBox Loader
16
- * Fetches payloads from PayloadsAllTheThings GitHub repository
20
+ * Get all available payload type names (canonical)
17
21
  */
18
-
22
+ declare function getPayloadBoxTypes(): PayloadBoxType[];
19
23
  /**
20
- * Supported PayloadBox types
24
+ * Get all short aliases
21
25
  */
22
- type PayloadBoxType = "xss" | "sql-injection" | "xxe" | "command-injection" | "open-redirect" | "path-traversal";
26
+ declare function getAliases(): Record<string, PayloadBoxType>;
23
27
  /**
24
- * Get available PayloadBox types
28
+ * Resolve a user-provided name to a canonical PayloadBox type.
29
+ *
30
+ * Accepts:
31
+ * "xss" → "xss"
32
+ * "sqli" → "sql-injection"
33
+ * "sql-injection" → "sql-injection"
34
+ * "cmd" → "command-injection"
35
+ *
36
+ * Returns null if the name doesn't match any known type.
25
37
  */
26
- declare function getPayloadBoxTypes(): PayloadBoxType[];
38
+ declare function resolvePayloadType(name: string): PayloadBoxType | null;
27
39
  /**
28
- * Load payloads from PayloadBox
40
+ * Check if a name resolves to a valid PayloadBox type
41
+ */
42
+ declare function isValidPayloadName(name: string): boolean;
43
+ /**
44
+ * Get description for a payload type
45
+ */
46
+ declare function getDescription(type: PayloadBoxType): string;
47
+ /**
48
+ * Load payloads from PayloadBox.
29
49
  *
30
- * @param type - PayloadBox type (xss, sql-injection, etc.)
31
- * @param limit - Maximum number of payloads to include
32
- * @param fetchFn - Fetch function to use (for testing/DI)
50
+ * Accepts both canonical names and short aliases:
51
+ * loadPayloadBox("xss") → fetches XSS payloads
52
+ * loadPayloadBox("sqli") → fetches SQL injection payloads
33
53
  */
34
- declare function loadPayloadBox(type: string, limit?: number, fetchFn?: typeof fetch): Promise<RuntimePayload>;
54
+ declare function loadPayloadBox(name: string, limit?: number, fetchFn?: typeof fetch): Promise<RuntimePayload>;
55
+ /**
56
+ * Clear PayloadBox cache
57
+ */
58
+ declare function clearPayloadBoxCache(): void;
35
59
 
36
60
  /**
37
61
  * File Loader
@@ -51,10 +75,12 @@ declare function loadFromFile(filePath: string): Promise<RuntimePayload[]>;
51
75
  * @vulcn/plugin-payloads
52
76
  * Official payload loader plugin for Vulcn
53
77
  *
54
- * Provides:
55
- * - Built-in payloads (XSS, SQLi, SSRF, XXE, etc.)
56
- * - PayloadBox loader (PayloadsAllTheThings)
57
- * - Custom file loader (YAML/JSON)
78
+ * Payload sources (in order of priority):
79
+ * 1. PayloadBox — community-curated payloads from PayloadsAllTheThings (default)
80
+ * 2. Custom files — expert-provided YAML/JSON payload files
81
+ *
82
+ * Short aliases for payload types:
83
+ * xss, sqli, xxe, cmd, redirect, traversal
58
84
  */
59
85
 
60
86
  /**
@@ -62,49 +88,32 @@ declare function loadFromFile(filePath: string): Promise<RuntimePayload[]>;
62
88
  */
63
89
  declare const configSchema: z.ZodObject<{
64
90
  /**
65
- * Include built-in payloads (default: true)
66
- */
67
- builtin: z.ZodDefault<z.ZodBoolean>;
68
- /**
69
- * Specific built-in payload names to include (if not all)
70
- */
71
- include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
72
- /**
73
- * Built-in payload names to exclude
74
- */
75
- exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
76
- /**
77
- * PayloadBox types to fetch from PayloadsAllTheThings
78
- * e.g., ["xss", "sql-injection", "xxe"]
91
+ * Payload types to load from PayloadsAllTheThings.
92
+ * Accepts short aliases: xss, sqli, xxe, cmd, redirect, traversal
93
+ * @example ["xss", "sqli"]
79
94
  */
80
- payloadbox: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
95
+ types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
81
96
  /**
82
- * Limit per PayloadBox type
97
+ * Maximum payloads per type (default 50)
83
98
  */
84
- payloadboxLimit: z.ZodDefault<z.ZodNumber>;
99
+ limit: z.ZodDefault<z.ZodNumber>;
85
100
  /**
86
101
  * Custom payload files to load (YAML/JSON)
87
102
  */
88
103
  files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
89
104
  }, "strip", z.ZodTypeAny, {
90
- builtin: boolean;
91
- payloadboxLimit: number;
92
- include?: string[] | undefined;
93
- exclude?: string[] | undefined;
94
- payloadbox?: string[] | undefined;
105
+ limit: number;
106
+ types?: string[] | undefined;
95
107
  files?: string[] | undefined;
96
108
  }, {
97
- builtin?: boolean | undefined;
98
- include?: string[] | undefined;
99
- exclude?: string[] | undefined;
100
- payloadbox?: string[] | undefined;
101
- payloadboxLimit?: number | undefined;
109
+ types?: string[] | undefined;
110
+ limit?: number | undefined;
102
111
  files?: string[] | undefined;
103
112
  }>;
104
113
  type PayloadsPluginConfig = z.infer<typeof configSchema>;
105
114
  /**
106
- * Payloads Plugin - loads payloads from various sources
115
+ * Payloads Plugin
107
116
  */
108
117
  declare const plugin: VulcnPlugin;
109
118
 
110
- export { BUILTIN_PAYLOADS, type PayloadsPluginConfig, plugin as default, getPayloadBoxTypes, loadFromFile, loadFromFiles, loadPayloadBox };
119
+ export { type PayloadsPluginConfig, clearPayloadBoxCache, plugin as default, getAliases, getDescription, getPayloadBoxTypes, isValidPayloadName, loadFromFile, loadFromFiles, loadPayloadBox, resolvePayloadType };