# Graybox Assessment ## Overview Takumi's graybox assessment feature receives both the source code of an application and the URL of the running instance that serves it. Takumi analyzes the source code to find candidate vulnerabilities, attacks the running application to confirm which of them actually reproduce, and outputs the results as a report on the web. It can be used from the Shisho Cloud byGMO web interface. Only candidate vulnerabilities that dynamic verification reproduced are reported as findings. The rest are recorded in a separate section of the report, so you can read the vulnerabilities that reproduced apart from those that did not. See [How to Read the Report](#report-structure) for details. ## Organization or Target Ownership Verification Graybox assessments send requests to a running application, so before starting one you need to verify your organization or prove ownership of the target application. For details, please refer to "[Pre-Assessment Organization Verification or Ownership Verification](/docs/t/assessment/features/assessment-authentication.md)". ## How to Start an Assessment Click "Assessments" in the sidebar, then click the "Create Assessment" button in the upper right corner of the screen to start an assessment. ![Assessment Start UI](/docs/_md-assets/aca0f31d96-start.png) ### Basic Settings - Enter a name to identify the assessment in "Assessment Name". - Select the report language (English or Japanese) in "Report Language". - Select "Graybox Assessment" as the assessment method. ### Assessment Type You can select one of the following two modes: - **Full Assessment** mode: Feature enumeration and the initial scan of the target source code are performed in one seamless process. After completion, the assessment pauses in a "Pending" state. See [Reviewing Results and Running Additional Scans](#reviewing-results-and-running-additional-scans) for next steps. - **Scoped Assessment** mode: Features are first enumerated from the target codebase. Once complete, the enumerated features are displayed. You can then select which features to assess and set priorities before starting the scan. ### Credit Threshold Credit thresholds can be set separately for feature enumeration and scanning (for "Scoped Assessment" mode, only feature enumeration). Takumi performs feature enumeration and scanning within the specified credit thresholds. The minimum for the scan threshold is 40 credits, which is higher than for a whitebox assessment. A graybox scan splits this budget between static analysis and the dynamic verification that follows it, so it needs more room to reach a verified result. ### Source Code Configuration You can provide source code using one of the following methods: #### GitHub Repositories You can specify one or more GitHub repositories. Click the "Add Repositories" button to add repositories for assessment. You can specify the branch of the target repository. If not specified, the repository's default branch will be used for assessment. #### File Upload You can upload source code archives directly. This is useful when GitHub integration is not available or for assessing local codebases. - **Supported formats**: `.zip` or `.tar.gz` - Click the "Upload Files" button to select and upload your archive - The extracted root directory will be displayed and used for file scope specification below ### File Scopes You can specify file paths to include in or exclude from the assessment. All file paths support glob patterns (e.g., `src/auth/**`, `backend/services/**`). Leaving the scope empty will assess the entire codebase. #### Include Scopes - Select the target repository or uploaded file in "Target" - Specify a feature category in "Feature Type" (optional) (e.g., `authentication`, `payments`, `api`) - Specify file paths to include in "File Path" Please note that even if specified as an assessment target, file paths may be excluded based on Takumi's judgment. #### Exclusions - Select the target repository or uploaded file in "Target" - Document the reason for exclusion in "Reason" (optional) (e.g., "Test code", "Auto-generated files") - Specify file paths to exclude in "File Path" ### Application Settings These settings describe the running application that dynamic verification works against. - Enter the URL of the running application that serves the source code you selected above in "Target URL". You can add more than one, which is useful when a single source tree serves several origins (for example, a web front end and its API on separate hosts). - Specify URLs to exclude from the scope of dynamic verification in "Out-of-Scope URLs". - Configure the credentials used to sign into the application in "In-App Authentication". You can provide an ID and password, or select "Other" and describe the authentication procedure in free form. "Account Type" (for example, admin or regular user) tells Takumi which role the credentials represent. :::info Out-of-Scope URLs are used to decide what dynamic verification treats as a target. Even a URL that is out of scope may still be accessed by Takumi during the assessment. Note that this setting does not completely block such access. ::: ## Reviewing Feature Enumeration Results When feature enumeration completes in "Scoped Assessment" mode, a matrix of detected features and assessment perspectives is displayed. On this screen, you can set the credit threshold for scanning and assessment priorities for each feature and perspective. You can set priorities of "Auto, High, Medium, Low, None" for each combination of feature and perspective. Higher-priority items are scanned first. When "Auto" is selected, Takumi automatically determines the priority based on risk analysis. After completing the configuration, click the "Start Pentesting" button to begin the scan. ## Reviewing Results and Running Additional Scans When the specified credit threshold is reached during a scan or scanning for all combinations is complete, the assessment pauses in a "Pending" state. Opening a "Pending" assessment displays the matrix screen again. From this screen, you can: - **Preview the interim report**: Click "Preview Report" to open the current report in a new tab. You can use it to review findings so far and decide whether to continue scanning or complete the assessment - **Run additional scans**: Set the credit threshold and priorities for unscanned combinations, then click "Start Pentesting" to run additional scans - **Complete the assessment**: If no additional scans are needed, click the "Complete Assessment" button to finalize the assessment ### Completing the Assessment Clicking "Complete Assessment" transitions you to the assessment report page. ### Checking Assessment Results Assessment reports can be viewed on the web. Each item in the assessment results explains which feature was assessed from what perspective, what severity and risk the vulnerability carries, and how dynamic verification confirmed it. ### Exporting a PDF Report {#pdf-report} You can download the assessment report as a PDF with a branded cover page. Click the **"Issue PDF Report"** button on the assessment report page and choose a cover page language (English or Japanese). Once the PDF is ready, a download link will be sent to the email address associated with your account. Download links expire after 15 minutes. If a link expires, click the download button again to get a new one. Note that issued PDFs are deleted after 30 days, so save a local copy if needed. ## Assessment Perspectives Static analysis in a graybox assessment reviews the code from the same perspectives as a [whitebox assessment](/docs/t/assessment/features/whitebox-assessment.md#assessment-perspectives). **Feature-Level Assessment** - Injection - File System Vulnerabilities - XSS - Broken Authorization - Business Logic Flaws **Repository-Level Assessment** - Misconfiguration - Broken Authentication Vulnerabilities such as Injection and XSS are tested for each feature identified by Takumi in advance to ensure the comprehensiveness of the assessment. On the other hand, perspectives such as Misconfiguration and Broken Authentication, which tend to exist in specific locations (e.g., configuration files or middleware layers) rather than being scattered across individual features, are executed only once for the entire target. Each candidate vulnerability raised from these perspectives is then attacked against the running application, and only those that reproduce are reported as findings. Whether one reproduces depends on the state of the running application, so a candidate that static analysis raises correctly may still fail to reproduce — for example, when the affected feature requires data or a privilege the provided credentials do not have. For the correspondence between these perspectives and OWASP ASVS 5.0, see [Compliance with OWASP ASVS 5.0](/docs/t/assessment/features/whitebox-assessment.md#asvs). ## How to Read the Report {#report-structure} The report is organized around what dynamic verification established. - **Analyzed Features** lists the features that static analysis examined, so you can see the coverage of the assessment. - **Findings List** contains the vulnerabilities that dynamic verification reproduced. Each finding carries a verification result describing what the verification established, followed by the reproduction steps it performed. The steps are written so that you can follow them yourself to see the vulnerability. - **Unconfirmed Findings** contains the candidate vulnerabilities that static analysis raised but dynamic verification could not reproduce. Reproduction steps are not included here, because nothing was reproduced. ## Regarding Credit Consumption {#credits} Credits are required to use this feature. Credit consumption varies depending on the characteristics and size of the assessment target. As a rough guide, each combination of a "feature" and a "perspective" (corresponding to a specific cell on the configuration screen) typically consumes approximately **5–8 credits**. However, actual consumption also varies depending on factors such as the scale of the target feature and the number of clues Takumi discovers during the assessment, so it may fall outside this range. You can set credit thresholds for the feature enumeration phase and the scanning phase separately when starting an assessment. Each phase's consumption will not exceed its specified threshold. Note that while an assessment is running, the credit limit you specified is reserved from your balance in advance, so the displayed credit balance is the value after deducting the reserved amount. See [Credit Reservation While a Run Is in Progress](/docs/t/assessment/billing/pricing.md#credit-reservation) for details.