debase

A CLI tool to decode base64 strings (especially IOCs) in JavaScript files while preserving original formatting. Great for security researcher that want to quickly translate encoded files, and defang them when necessary. Also supports comments so you know what debase has done. You can use this as a CLI tool or as a library. Works for JavaScript, Python, Ruby and PHP.

Installation

Global installation

npm install debase -g

Local usage

debase ./example.js

Usage

CLI Usage

debase [--defang] [--comment|-c] example.js

The tool will output the file content with all base64 strings decoded to stdout.

Options

• --defang - Defang URLs and IP addresses in decoded output (converts http:// to hxxp://, dots to [.])
• --comment, -c - Add // Decoded by debase comment to each line that was decoded

Examples

Basic usage:

Input file (malicious.js):

const payload = "Y29uc29sZS5sb2coJ0hlbGxvJyk=";
const data = Buffer.from('c2VjcmV0', 'base64');
const decoded = atob('dGVzdA==');
let file = 'LmVudg=='.toString();

Run:

debase malicious.js

Output:

const payload = "console.log('Hello')";
const data = "secret";
const decoded = "test";
let file = '.env';

With defang option:

Input file with malicious URLs:

const c2 = 'aHR0cDovLzEwLjIwNS4zMS4yMjo1NTgwL2NvcmUtaGVscGVy'.toString();
const url = Buffer.from('aHR0cHM6Ly9tYWxpY2lvdXMuZG9tYWluLmNvbS9wYXlsb2Fk', 'base64');

Run:

debase --defang malicious.js

Output:

const c2 = 'hxxp://10[.]205[.]31[.]22:5580/core-helper';
const url = 'hxxps://malicious[.]domain[.]com/payload';

With comment flag:

Input:

let path = 'Li4v';
const module = Buffer.from('ZnM=', 'base64');

Run:

debase --comment malicious.js

Output:

let path = '../';  // Decoded by debase
const module = 'fs';  // Decoded by debase

Combined options:

debase --defang --comment malicious.js
debase -c --defang malicious.js

Redirect to file

To save the output to a new file:

debase input.js > output.js
debase --defang malicious.js > defanged-output.js

Library Usage

You can also import and use debase as a library in your Node.js projects:

import { decodeBase64Strings, isValidBase64, defangString } from 'debase';

// Decode base64 strings in code
const obfuscatedCode = `
  const secret = 'aGVsbG8='.toString();
  const data = Buffer.from('d29ybGQ=', 'base64');
`;

const decodedCode = decodeBase64Strings(obfuscatedCode);
console.log(decodedCode);
// Output:
//   const secret = 'hello';
//   const data = 'world';

// Decode with defang enabled
const malwareCode = `
  const c2 = Buffer.from('aHR0cDovLzEwLjIuMy40OjgwODA=', 'base64');
`;

const defangedCode = decodeBase64Strings(malwareCode, { defang: true });
console.log(defangedCode);
// Output:
//   const c2 = 'hxxp://10[.]2[.]3[.]4:8080';

// Decode with comments for validation
const suspiciousCode = `let path = 'Li4v';`;
const commented = decodeBase64Strings(suspiciousCode, { addComments: true });
console.log(commented);
// Output:
//   let path = '../';  // Decoded by debase

// Validate if a string is base64
if (isValidBase64('SGVsbG8gV29ybGQ=')) {
  console.log('Valid base64!');
}

// Manually defang a string
const url = 'https://malicious.example.com/payload';
const defanged = defangString(url);
console.log(defanged);
// Output: hxxps://malicious[.]example[.]com/payload

API Reference

decodeBase64Strings(content: string, options?: object): string

• Decodes all base64 strings found in the input content
• Returns the content with base64 strings replaced by their decoded values
• Preserves original formatting and quotes
• Options:
  • defang (boolean): If true, defangs URLs and IP addresses in decoded output (default: false)
  • addComments (boolean): If true, adds // Decoded by debase to modified lines (default: false)

isValidBase64(str: string): boolean

• Validates whether a string is valid base64
• Returns true if the string can be successfully decoded and re-encoded
• Returns false otherwise

defangString(str: string): string

• Defangs URLs and IP addresses in a string
• Converts http:// to hxxp:// and https:// to hxxps://
• Replaces dots in IP addresses and domain names with [.]
• Returns the defanged string

How it works

The tool:

1. Scans for base64 strings in multiple contexts:
   • Long quoted strings (20+ chars): "SGVsbG8gV29ybGQgVGhpcyBpcyBh..."
   • Short padded strings (3+ chars with = or ==): 'LmVudg=='
   • Short suspicious strings (3-19 chars): 'Li4v' - only decoded if content is interesting (path traversal, commands, modules, etc.)
   • Buffer.from() calls: Buffer.from('SGVsbG8=', 'base64')
   • Buffer.from().toString() chains: Buffer.from('ZnM=', 'base64').toString()
   • atob() calls: atob('SGVsbG8=')
   • .toString() patterns: 'SGVsbG8='.toString() (common obfuscation)
2. Validates that the strings are actually base64-encoded
3. For short strings without padding, checks if decoded content is "interesting":
   • Path traversal sequences (../, ..\\)
   • Common suspicious files (.env, .git, passwd, shadow, etc.)
   • Commands (curl, wget, bash, eval, exec, etc.)
   • Module names (fs, http, child_process, etc.)
   • File extensions (.js, .py, .sh, .exe, etc.)
4. Decodes valid base64 strings
5. Optionally defangs URLs and IP addresses in decoded output (with --defang flag)
6. Replaces them with their decoded versions while preserving quotes and formatting
7. Escapes special characters in decoded strings (newlines, quotes, etc.)

Features

• ✅ Preserves original file formatting
• ✅ Handles single quotes, double quotes, and backticks
• ✅ Detects long base64 strings (20+ characters)
• ✅ Detects short padded base64 strings (= or == padding is a strong signal)
• ✅ Intelligently detects short suspicious base64 (path traversal, commands, modules)
• ✅ Decodes Buffer.from(data, 'base64') patterns
• ✅ Decodes Buffer.from(data, 'base64').toString() chains
• ✅ Decodes atob(data) patterns
• ✅ Decodes 'data'.toString() patterns (common in obfuscated code)
• ✅ Optional defanging of URLs and IP addresses for safe analysis
• ✅ Validates base64 before decoding (avoids false positives)
• ✅ Escapes special characters in decoded output
• ✅ Works as both CLI tool and importable library

Use Cases

• Malware analysis: Decode obfuscated malicious code
• Security research: Analyze suspicious npm packages or scripts
• Code review: Understand what encoded strings actually contain
• Debugging: Quickly decode base64 data in source files

License

MIT