@ts-graphviz/adapter 3.0.3 → 3.0.4-next-2175a0b15ee57f675a1fda902b74d8359a5c05cb

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @ts-graphviz/adapter
 
+## 3.0.4-next-2175a0b15ee57f675a1fda902b74d8359a5c05cb
+
+### Patch Changes
+
+- [#1528](https://github.com/ts-graphviz/ts-graphviz/pull/1528) [`6966a66`](https://github.com/ts-graphviz/ts-graphviz/commit/6966a6699e87e2c74e7348aa6fdc2c50ae11b308) Thanks [@kamiazya](https://github.com/kamiazya)! - Add comprehensive security documentation for safe usage of adapter options
+
+  This patch adds security considerations and best practices documentation to clarify the safe usage of `dotCommand`, `library`, and user-provided DOT files.
+
+  **Changes:**
+
+  - Added security considerations section to README explaining spawn/Deno.Command behavior
+  - Added JSDoc security notes to `dotCommand` and `library` type definitions
+  - Included validation example showing how to sanitize user-uploaded DOT files using @ts-graphviz/ast
+  - Documented potentially dangerous attributes that can access file system resources
+
+  **Documentation Clarifications:**
+
+  - Explains that spawn/Deno.Command do not invoke shell interpreters, preventing shell injection
+  - Clarifies that configuration options should be controlled by developers, not end-users
+  - Provides working TypeScript example for validating and sanitizing untrusted DOT content
+  - Lists file-access attributes (image, shapefile, fontpath, etc.) that require validation
+
+  This documentation addresses security concerns while maintaining that the library itself has no vulnerabilities when used as designed.
+
 ## 3.0.3
 
 ### Patch Changes

package/README.md

@@ -93,6 +93,121 @@ await toFile(dot, './result.svg', { format: 'svg' });
 
 Both functions accept configuration options to customize the rendering process.
 
+## Configuration Options
+
+### Security Considerations
+
+The `dotCommand` and `library` options are intended to be configured by application developers, not derived from end-user input:
+
+- **`dotCommand`**: Specifies the path to the Graphviz executable. This should be a trusted, hardcoded path in your application configuration.
+- **`library`**: Specifies external libraries to load. These should be trusted library names defined in your application code.
+
+**Important**: This library executes external commands using `spawn` (Node.js) or `Deno.Command` (Deno), which do not invoke a shell interpreter. This prevents shell injection attacks through metacharacters (`;`, `` ` ``, `|`, `$`, etc.). However, these options should not be exposed to end-user input.
+
+#### Processing User-Provided DOT Files
+
+When rendering DOT files uploaded by users or generated from user input, implement validation before passing them to this library:
+
+**Validation Steps**:
+1. **Syntax validation**: Verify the DOT file is well-formed and parseable
+2. **Attribute filtering**: Check for potentially dangerous attributes that reference file system resources:
+   - `image`, `shapefile` - Can reference arbitrary image files
+   - `fontpath`, `fontname` - Can reference font files
+   - `imagepath` - Defines search path for images
+3. **Content sanitization**: Consider using a DOT parser to rebuild the graph with only allowed attributes
+4. **Sandboxing**: Run Graphviz in a sandboxed environment with restricted file system access when processing untrusted input
+
+**Example Risk Scenario**:
+
+⚠️ **Warning**: The following is an example of **unsafe** DOT content that should be rejected by validation:
+
+```dot
+digraph G {
+  node [image="/etc/passwd"];  // ⚠️ DANGEROUS: Attempts to access sensitive file
+  node1;
+}
+```
+
+While Graphviz will handle file access errors gracefully, processing untrusted DOT files without validation may expose information about your file system or cause unexpected behavior. **Always validate and sanitize user-provided DOT files before processing.**
+
+**Example: Validating and Sanitizing User-Provided DOT Files**
+
+Here's an example of how to use the `@ts-graphviz/ast` package to parse, validate, and sanitize DOT files:
+
+```typescript
+import { parse, stringify } from '@ts-graphviz/ast';
+
+// Potentially dangerous attributes that can access file system
+const DANGEROUS_ATTRIBUTES = new Set([
+  'image',
+  'shapefile',
+  'fontpath',
+  'fontname',
+  'imagepath',
+]);
+
+/**
+ * Validates and sanitizes a DOT file by removing dangerous attributes
+ */
+function validateAndSanitizeDOT(dotString: string): string {
+  try {
+    // Parse the DOT string into an AST
+    const ast = parse(dotString);
+
+    // Remove dangerous attributes from the AST
+    sanitizeAST(ast);
+
+    // Convert back to DOT string
+    return stringify(ast);
+  } catch (error) {
+    throw new Error(`Invalid DOT syntax: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively sanitize AST nodes by removing dangerous attributes
+ */
+function sanitizeAST(node: any): void {
+  if (!node || typeof node !== 'object') return;
+
+  // Handle nodes with children
+  if (Array.isArray(node.children)) {
+    node.children = node.children.filter((child: any) => {
+      // Filter out dangerous attribute nodes
+      if (child.type === 'Attribute') {
+        const attributeName = child.key?.value;
+        if (DANGEROUS_ATTRIBUTES.has(attributeName)) {
+          console.warn(`Removed dangerous attribute: ${attributeName}`);
+          return false;
+        }
+      }
+      // Recursively sanitize child nodes
+      sanitizeAST(child);
+      return true;
+    });
+  }
+}
+
+// Usage example
+const userUploadedDOT = `
+  digraph G {
+    node [image="/etc/passwd"];
+    node1 [label="Safe label"];
+  }
+`;
+
+const sanitizedDOT = validateAndSanitizeDOT(userUploadedDOT);
+// Result: digraph G { node1 [label="Safe label"]; }
+```
+
+**Best Practices**:
+- Use the default `dot` command when possible
+- If you need to customize `dotCommand`, use a hardcoded path or environment variable controlled by the deployment environment
+- Do not allow end-user input to control the configuration options
+- Validate and sanitize DOT strings from untrusted sources before rendering
+- Consider using a whitelist approach for allowed attributes when processing user-provided DOT files
+- Run Graphviz in a restricted environment when handling untrusted input
+
 ## Contributors 👥
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

package/lib/types.d.ts

@@ -98,6 +98,10 @@ export interface CommonOptions {
     suppressWarnings?: boolean;
     /**
      * Path of graphviz dot command.
+     *
+     * **This should be a trusted, hardcoded path in your application configuration. Do not derive this value from end-user input.**
+     *
+     * @defaultValue 'dot'
      */
     dotCommand?: string;
     attributes?: {
@@ -120,6 +124,8 @@ export interface CommonOptions {
     scale?: number;
     /**
      * Use external library.
+     *
+     * **These should be trusted library names defined in your application code. Do not derive these values from end-user input.**
      */
     library?: string[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-graphviz/adapter",
-  "version": "3.0.3",
+  "version": "3.0.4-next-2175a0b15ee57f675a1fda902b74d8359a5c05cb",
   "description": "Graphviz Runtime adapters for Cross Platform",
   "keywords": [
     "graphviz",