Ghostwriter Client

Node.js GraphQL API client for Ghostwriter penetration test reporting platform.

Automate professional penetration test report generation, finding management, and client delivery workflows.

✨ Features

• ✅ Authentication - JWT-based login and token management
• ✅ Report Management - Create, read, update reports
• ✅ Findings - Create, manage, and query security findings
• ✅ Clients & Projects - List and query available clients and projects
• ✅ Schema Introspection - Discover GraphQL schema at runtime
• ✅ DOCX Formatting - Auto-format rich text for professional document export
• ✅ Error Handling - Comprehensive error messages and validation
• ✅ Self-Signed Certs - Support for self-signed SSL certificates
• ✅ Severity Mapping - Automatic severity level translation

📦 Installation

npm

npm install ghostwriter-client

From Git

git clone https://github.com/yourusername/ghostwriter-client.git
cd ghostwriter-client
npm install

🚀 Quick Start

Basic Usage

const GhostwriterClient = require('ghostwriter-client');

// Initialize client
const gw = new GhostwriterClient({
  url: process.env.GHOSTWRITER_URL,
  username: process.env.GHOSTWRITER_USERNAME,
  password: process.env.GHOSTWRITER_PASSWORD
});

// Authenticate
await gw.authenticate();
console.log('✓ Connected to Ghostwriter');

// Get projects
const projects = await gw.getProjects();
console.log(`Found ${projects.length} projects`);

// Create a report
const report = await gw.createReport(projectId, 'Penetration Test Report');
console.log(`Created report: ${report.id}`);

// Add findings
await gw.createFinding(report.id, {
  title: 'SQL Injection Vulnerability',
  severity: 'critical',
  description: 'Application is vulnerable to SQL injection',
  impact: 'Unauthorized database access',
  mitigation: 'Use parameterized queries'
});

Environment Variables

GHOSTWRITER_URL=https://ghostwriter.example.com/v1/graphql
GHOSTWRITER_USERNAME=admin
GHOSTWRITER_PASSWORD=your-password

📚 API Documentation

Core Methods

Authentication

await gw.authenticate(username, password);
const user = await gw.whoami();
await gw.healthCheck();

Clients & Projects

const clients = await gw.getClients();
const client = await gw.getClient(clientId);
const projects = await gw.getProjects();
const project = await gw.getProject(projectId);

Reports

const reports = await gw.getReports(projectId);
const report = await gw.createReport(projectId, title, options);
await gw.updateReport(reportId, updates);

Findings

const findings = await gw.getFindings(reportId);
await gw.createFinding(reportId, finding);
await gw.createFindings(reportId, findingsArray);
await gw.updateFinding(findingId, updates);

Schema

const fields = await gw.introspectSchema();

📖 Examples

Full Integration Test

GHOSTWRITER_URL='https://...' \
GHOSTWRITER_USERNAME='admin' \
GHOSTWRITER_PASSWORD='password' \
node examples/full-test.js

Create a Report with Findings

node examples/test-create-report.js

Introspect GraphQL Schema

node scripts/test-schema.js

Check Schema Input Types

node examples/check-input-type.js report_insert_input

See examples/ directory for more samples.

🔧 Configuration

Self-Signed Certificates

The client automatically accepts self-signed SSL certificates. To require certificate validation:

const gw = new GhostwriterClient({
  url: 'https://ghostwriter.example.com/v1/graphql',
  username: 'admin',
  password: 'password',
  rejectUnauthorized: true
});

Custom Options

const gw = new GhostwriterClient({
  url: process.env.GHOSTWRITER_URL,
  username: process.env.GHOSTWRITER_USERNAME,
  password: process.env.GHOSTWRITER_PASSWORD,
  token: process.env.GHOSTWRITER_TOKEN,  // Optional: use existing token
  timeout: 30000                          // Request timeout in ms
});

🐛 Troubleshooting

Connection Issues

# Test connection
node scripts/test-connection.js

# Test authentication
node examples/basic-auth.js

Schema Errors

# Discover available fields
node scripts/test-schema.js

# Check specific input type
node examples/check-input-type.js report_insert_input

Known Issues

See GHOSTWRITER_BLOCKERS.md for known limitations and workarounds.

📝 Documentation

• SKILL.md - Comprehensive API reference
• SETUP.md - Installation and configuration guide
• INTEGRATION_GUIDE.md - Integrating with your applications
• GHOSTWRITER_BLOCKERS.md - Known issues and solutions

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Ghostwriter - Professional penetration test reporting platform
• Hasura - GraphQL engine for PostgreSQL

📞 Support

For issues and questions:

• GitHub Issues: Report a bug
• Discussions: Ask a question

---

Made with ❤️ for penetration testers