Pentest Notes Best Practices: How to Guide TurboPentest's AI Agents

The Notes field on the pentest setup page is one of the most underused features in TurboPentest. A well-written note can be the difference between a surface-level scan and a deep, targeted assessment that finds the vulnerabilities that matter. This guide covers exactly what to include and how to format your notes for the best results.

Why Notes Matter

TurboPentest runs 14 security tools across your attack surface, and Paladin AI coordinates the results. When you provide notes, you give the agents context that tools alone cannot discover: where your application stores sensitive data, which endpoints require authentication, what areas you are most concerned about, and where to look for business logic flaws.

Without notes, TurboPentest still delivers a thorough pentest. With good notes, it delivers a targeted one.

Providing Authentication Credentials

Authenticated testing is one of the biggest force multipliers. Without credentials, the agents can only test what is publicly accessible. With credentials, they can test every authenticated endpoint, admin panel, and user-specific workflow.

How to Format Credentials

Login credentials:
- Admin: admin@example.com / S3cureP@ss!
- Regular user: user@example.com / TestUser123
- API key: Bearer sk-test-abc123def456

Tips for Credentials

• Create test accounts specifically for pentesting rather than using production credentials. This avoids locking out real users if an account gets rate-limited.
• Include multiple roles if your application has role-based access control. Provide an admin account, a regular user account, and any other role (editor, viewer, moderator) so the agents can test privilege escalation between roles.
• Specify the login URL and method if it is not obvious. For example: "Login at /api/v2/auth/login with POST body { email, password }" or "Login at /admin/login using the form."
• Include API keys or tokens if your application uses token-based auth. Specify the header format: "Use Authorization: Bearer <token>" or "Use X-API-Key: <key>."
• Mention MFA if multi-factor authentication is enabled. If MFA is on test accounts, either disable it for the pentest or provide the TOTP secret so the agents can generate codes.

Sharing Swagger and API Documentation

If your application has an API, providing the Swagger/OpenAPI spec gives Paladin AI a complete map of every endpoint, parameter, and expected request format. This dramatically improves API coverage.

How to Share API Docs

Swagger/OpenAPI spec available at:
- https://api.example.com/docs/swagger.json
- Or: https://api.example.com/v2/openapi.yaml

API base URL: https://api.example.com/v2

Tips for API Documentation

• Link directly to the spec file (JSON or YAML) rather than the Swagger UI page. The agents can parse the raw spec more effectively.
• Mention the API version if multiple versions coexist, and specify which version should be the focus.
• Call out undocumented endpoints that are not in the spec but exist in production. For example: "There is also a legacy /api/v1/users/export endpoint that is not in the Swagger spec."
• Note any rate limits so the agents can pace requests and avoid getting blocked.

Directory Listings and Application Maps

Telling the agents where to look saves time and ensures critical areas are not missed.

How to Provide Structure

Key paths to test:
- /admin/* — admin panel (use admin credentials above)
- /api/v2/* — main API (see Swagger link above)
- /uploads/ — user file upload directory
- /internal/debug — debug endpoint, should not be public
- /.well-known/ — check for exposed config files

File upload is at: /dashboard/settings/import (accepts CSV and JSON)
WebSocket endpoint: wss://app.example.com/ws/realtime

Tips for Directory Listings

• Highlight sensitive areas like admin panels, payment processing, file uploads, and user data export endpoints.
• Mention hidden or internal endpoints that automated crawling might not discover. Debug endpoints, health checks, and internal tools are common targets.
• Specify any path-based access controls so the agents can test whether they are properly enforced. For example: "Only admins should access /admin/*, regular users should get 403."
• List subdomains if you know of staging, development, or internal subdomains that share infrastructure with production.

Highlighting Areas of Concern

If you already know where your risk is concentrated, say so. This helps the agents prioritize.

How to Describe Concerns

Areas of concern:
- We recently migrated the payment flow — please test /checkout/* thoroughly
- The file upload at /api/files/upload accepts user files — check for unrestricted upload
- User profile pages render markdown — concerned about stored XSS
- The password reset flow at /auth/reset was built in-house, not using a library

Tips for Describing Concerns

• Be specific about what worries you. "Test everything" is less useful than "We store PII in the /api/users/export endpoint and want to make sure it requires proper authorization."
• Mention recent changes. New code has the highest probability of containing vulnerabilities. If you just shipped a new feature, point the agents at it.
• Reference compliance requirements if applicable. "We need to pass PCI DSS — focus on payment data handling and encryption" tells the agents what standard to evaluate against.
• Flag known issues you want verified. "We think there might be an IDOR on /api/orders/{id} — please confirm" gives the agents a direct hypothesis to test.

Technology Stack Information

Knowing the stack helps the agents select the right attack techniques and vulnerability templates.

How to Describe Your Stack

Tech stack:
- Frontend: React 18 with Next.js 14
- Backend: Node.js with Express
- Database: PostgreSQL 15
- Auth: NextAuth.js with JWT sessions
- Hosting: AWS (ECS + RDS + S3)
- CDN: CloudFront

Tips for Stack Information

• Include framework versions when you know them. Vulnerability databases are version-specific.
• Mention your ORM or database access layer. Knowing whether you use raw SQL, Prisma, or Sequelize helps the agents assess SQL injection risk.
• List third-party integrations (Stripe, Auth0, SendGrid) since these often have their own attack surface through webhooks and callback URLs.
• Specify your hosting environment — cloud provider, containerized or not, load balancer type. This helps focus network-level testing.

Test Environment and Data Setup

The quality of your pentest depends on the quality of the environment it runs against. A production system with minimal data or a shared staging instance limits what the agents can find.

How to Describe Your Environment

Environment:
- Dedicated pentest instance at pentest.example.com (safe to test aggressively)
- Multi-tenant: Tenant A (acme-corp) and Tenant B (globex) — test cross-tenant access
  - Tenant A admin: admin@acme-corp.com / PentestA2026!
  - Tenant B user: user@globex.com / PentestB2026!
- Test data seeded: 500 users, 10k orders, file attachments in S3
- Stripe test mode enabled with key sk_test_xxx

Tips for Test Environments

• Provide accounts across multiple tenants if your application is multi-tenant. Cross-tenant data leakage is one of the most critical vulnerabilities in SaaS applications and it cannot be tested with a single tenant. Give the agents credentials for at least two tenants so they can verify that Tenant A cannot access Tenant B's data through API enumeration, shared endpoints, or parameter tampering.
• Seed a full set of test data that exercises the application realistically. Empty databases hide vulnerabilities — if there are no orders, the agents cannot test whether order access controls work. Populate users, transactions, file uploads, messages, and any other core data objects so the agents have real records to test against.
• Use a dedicated deployment if practical. A dedicated pentest environment lets the agents test aggressively — brute-force login endpoints, fuzz file uploads, probe rate limits — without affecting real users or triggering alerts to your operations team. If a dedicated deployment is not feasible, mention the constraints so the agents can throttle accordingly.
• Enable test modes for third-party services. If your app integrates with Stripe, Twilio, or other services, switch to their test/sandbox mode so the agents can exercise payment flows, SMS verification, and webhooks without real charges or messages.
• Mirror production configuration. The pentest environment should match production as closely as possible — same WAF rules, same CORS policy, same rate limits. Testing against a permissive staging environment produces findings that may not apply to production.

Special Instructions

Use notes to give the agents guardrails or expand their scope beyond the defaults.

Examples of Useful Special Instructions

Special instructions:
- Do NOT test /api/billing/charge — this endpoint processes real payments
- Focus 80% of effort on the API, 20% on the marketing site
- The staging environment at staging.example.com shares the same database — be careful with write operations
- Test the GraphQL endpoint at /graphql — the introspection query should be disabled in production
- Check if the /health endpoint exposes version numbers or internal IPs

Tips for Special Instructions

• Set boundaries on what should not be tested. If an endpoint triggers real emails, charges credit cards, or modifies production data, say so explicitly.
• Prioritize scope if your application is large. Telling the agents where to focus produces better results than testing everything at equal depth.
• Mention environment quirks like shared databases between staging and production, or services that go down during off-hours.

Putting It All Together

Here is an example of a well-structured note that combines everything:

## Auth
- Admin: admin@testcorp.com / Pentest2026!
- User: jane@testcorp.com / UserPass789
- Login: POST /api/auth/login { email, password }
- Admin panel: /admin (admin only)

## Multi-Tenant
- Tenant "Acme": acme-admin@testcorp.com / AcmeTest2026!
- Tenant "Globex": globex-user@testcorp.com / GlobexTest2026!
- Test cross-tenant access — Acme should never see Globex data

## Environment
- Dedicated pentest instance at pentest.testcorp.com
- Seeded with 200 users, 5k orders, file attachments across both tenants
- Stripe test mode active (sk_test_xxx)

## API
- Swagger: https://api.testcorp.com/v3/openapi.json
- Base URL: https://api.testcorp.com/v3
- Undocumented: GET /api/internal/metrics (should be restricted)

## Focus Areas
- File upload at /api/documents/upload — accepts PDF, DOCX, no size limit currently
- Password reset flow at /auth/forgot — custom implementation
- User search at /api/users/search — may be vulnerable to IDOR
- Recently added GraphQL at /graphql — introspection should be off

## Stack
- Next.js 14, Prisma, PostgreSQL 15, AWS ECS

## Boundaries
- Do NOT hit /api/billing/process — triggers real Stripe charges
- The WebSocket at /ws is experimental and may crash under load

This gives the agents everything they need: access, a map, hypotheses to test, and boundaries to respect.

Common Mistakes to Avoid

• Empty notes. Even a one-liner like "Focus on the API at /api/v2, credentials: test@example.com / pass123" is better than nothing.
• Stale credentials. If you rotated passwords since the last pentest, update the notes. Expired credentials waste scan time on failed authentication.
• Overly broad instructions. "Find all vulnerabilities" does not help — the agents are already doing that. Be specific about what matters most to you.
• Sensitive production credentials. Always use dedicated test accounts. Never paste production admin passwords, database connection strings, or cloud provider keys into notes.

Start Your Next Pentest

The Notes field accepts up to 5,000 characters — more than enough to cover credentials, API docs, focus areas, and special instructions. Next time you set up a pentest, spend two minutes writing targeted notes. The quality of your results will reflect it.

Start a new pentest with detailed notes and see the difference targeted guidance makes.