PhoneInfoga

https://github.com/sundowndev/phoneinfoga
Admin
PhoneInfoga is an advanced information gathering framework that scans international phone numbers to...
Tokens:17,375
Snippets:188
Trust Score:7.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Build Tools

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Installs necessary tools for building, creating mocks, and running tests.

```shell
# Install tools needed to build, creating mocks or running tests
$ make install-tools
```

--------------------------------

### Install MkDocs Dependencies

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Installs mkdocs and its necessary plugins for generating documentation.

```shell
python3 -m pip install mkdocs==1.3.0 mkdocs-material==8.3.9 mkdocs-minify-plugin==0.5.0 mkdocs-redirects==1.1.0
```

--------------------------------

### Install PhoneInfoga Globally

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Installs the downloaded PhoneInfoga binary to a global path for system-wide access.

```bash
sudo install ./phoneinfoga /usr/local/bin/phoneinfoga
```

--------------------------------

### Install PhoneInfoga via Script

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Use this script to download the latest release of PhoneInfoga. Add --help for installation options.

```bash
bash <( curl -sSL https://raw.githubusercontent.com/sundowndev/phoneinfoga/master/support/scripts/install )
# Add --help at the end of the command for a list of install options
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/sundowndev/phoneinfoga/blob/master/web/client/README.md

Run this command to install all necessary project dependencies using Yarn.

```bash
yarn install
```

--------------------------------

### Install PhoneInfoga with Homebrew

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Installs PhoneInfoga using the Homebrew package manager on macOS.

```shell
brew install phoneinfoga
```

--------------------------------

### Start PhoneInfoga REST API Server

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Launch the 'serve' command to start the REST API server, which also includes an optional Vue.js web client. Can be configured with custom ports, environment files, and disabled scanners.

```bash
# Start server on default port 5000
phoneinfoga serve
```

```bash
# Start server on custom port
phoneinfoga serve -p 8080
```

```bash
# Start REST API only (no web client)
phoneinfoga serve --no-client
```

```bash
# Start with custom environment file and disabled scanners
phoneinfoga serve -p 8080 --env-file=.env.local -D ovh
```

```bash
# Docker usage
docker run --rm -it -p 5000:5000 sundowndev/phoneinfoga serve
docker run --rm -it -p 8080:8080 sundowndev/phoneinfoga serve -p 8080 --no-client
```

```yaml
# Docker Compose configuration
# docker-compose.yml
# version: '3.7'
# services:
#     phoneinfoga:
#       container_name: phoneinfoga
#       restart: on-failure
#       image: sundowndev/phoneinfoga:latest
#       command:
#         - "serve"
#         - "--no-client"
#       ports:
#         - "80:5000"
#       environment:
#         - NUMVERIFY_API_KEY=your_key
#         - GOOGLECSE_CX=your_search_engine_id
#         - GOOGLE_API_KEY=your_google_api_key
```

--------------------------------

### Start Development Server

Source: https://github.com/sundowndev/phoneinfoga/blob/master/web/client/README.md

Compiles and hot-reloads the application for development purposes. Access the running application via your browser.

```bash
yarn serve
```

--------------------------------

### Go: Scan Phone Number with Google Search

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/go-module-usage.md

Example of how to initialize a number and use the Google Search scanner to find related links. Ensure you have the necessary imports.

```go
package main

import (
	"fmt"
	"log"

	"github.com/sundowndev/phoneinfoga/v2/lib/number"
	"github.com/sundowndev/phoneinfoga/v2/lib/remote"
)

func main() {
	n, err := number.NewNumber("...")
	if err != nil {
		log.Fatal(err)
	}
	
	res, err := remote.NewGoogleSearchScanner().Scan(n)
	if err != nil {
		log.Fatal(err)
	}
	
	links := res.(remote.GoogleSearchResponse)
	for _, link := range links.Individuals {
		fmt.Println(link.URL) // Google search link to scan
	}
}
```

--------------------------------

### Start PhoneInfoga Web Services

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Starts the PhoneInfoga web services in detached mode using docker-compose.

```shell
docker-compose up -d
```

--------------------------------

### Install Phoneinfoga Go Module

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/go-module-usage.md

Use this command to add the Phoneinfoga module to your Go project dependencies.

```bash
go get -v github.com/sundowndev/phoneinfoga/v2
```

--------------------------------

### OVH Scanner Example

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Shows an example of using the OVH scanner to check if a phone number belongs to OVH Telecom. No configuration is required.

```shell
$ phoneinfoga scan -n +3336517xxxx

Results for ovh
Found: true
Number range: 036517xxxx
City: Abbeville
```

--------------------------------

### Configure Scanners with Environment Variables

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Scanners can be configured using environment variables or `.env` files, particularly for API authentication. This example shows a basic `.env` file structure.

```bash
# .env file example
# Place in current directory or specify with --env-file flag

```

--------------------------------

### Test PhoneInfoga Version

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Verifies the installed PhoneInfoga version to ensure it is up-to-date.

```bash
./phoneinfoga version
```

--------------------------------

### REST API: GET /api/

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Check if the API service is healthy and get version information.

```APIDOC
## GET /api/

### Description
Check if the API service is healthy and get version information.

### Method
GET

### Endpoint
/api/

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the API is healthy.
- **version** (string) - The current version of the API.
- **commit** (string) - The git commit hash of the current build.
- **demo** (boolean) - Indicates if the API is running in demo mode.

#### Response Example
```json
{
  "success": true,
  "version": "v2.x.x",
  "commit": "abc123",
  "demo": false
}
```
```

--------------------------------

### Custom Formatting Examples (France)

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/resources/formatting.md

Showcases diverse custom formatting examples for French phone numbers, reflecting common online sharing practices.

```text
+3301 86 48 xx xx
```

```text
+33018648xxxx
```

```text
+33018 648 xxx x
```

```text
(0033)018648xxxx
```

```text
(+33)018 648 xxx x
```

```text
+33/018648xxxx
```

```text
(0033)018 648 xxx x
```

```text
+33018-648-xxx-x
```

```text
(+33)018648xxxx
```

```text
(+33)01 86 48 xx xx
```

```text
+33/018-648-xxx-x
```

```text
+33/01-86-48-xx-xx
```

```text
+3301-86-48-xx-xx
```

```text
(0033)01 86 48 xx xx
```

```text
+33/01 86 48 xx xx
```

```text
(+33)018-648-xxx-x
```

```text
(+33)01-86-48-xx-xx
```

```text
(0033)01-86-48-xx-xx
```

```text
(0033)018-648-xxx-x
```

```text
+33/018 648 xxx x
```

--------------------------------

### Local Scanner Output Example

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Demonstrates the output of the local scanner, which provides basic phone number formatting and country/carrier recognition. No specific configuration is required for this scanner.

```shell
$ phoneinfoga scan -n +4176418xxxx

Results for local
Raw local: 076418xxxx
Local: 076 418 xx xx
E164: +4176418xxxx
International: 4176418xxxx
Country: CH
```

--------------------------------

### Google Custom Search Engine (Googlecse) Scan Example

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Demonstrates how to use the Googlecse scanner to search for a phone number. Requires GOOGLE_API_KEY and GOOGLECSE_CX environment variables.

```shell
$ phoneinfoga scan -n +1241325xxxx

Results for googlecse
Homepage: https://cse.google.com/cse?cx=<redacted>
Result count: 1
Items:
    Title: Info about +1241325xxxx
    URL: https://example.com/1241325xxxx
```

--------------------------------

### Run Googlesearch Scan

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Example of how to run the Googlesearch scanner with a phone number. This command generates Google search URLs for manual review.

```shell
$ phoneinfoga scan -n +4176418xxxx
```

--------------------------------

### Custom Formatting Examples (US)

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/resources/formatting.md

Provides various custom formatting examples for US-based phone numbers. These formats reflect common ways numbers are shared online and may differ from strict E.164.

```text
+1 618-555-xxxx
```

```text
(+1)618-555-xxxx
```

```text
+1/618-555-xxxx
```

```text
(618) 555xxxx
```

```text
(618) 555-xxxx
```

```text
(618) 555.xxxx
```

```text
(618)555xxxx
```

```text
(618)555-xxxx
```

```text
(618)555.xxxx
```

--------------------------------

### Docker Compose for PhoneInfoga

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Defines a docker-compose setup to run PhoneInfoga as a service, exposing port 80.

```yaml
version: '3.7'

services:
    phoneinfoga:
      container_name: phoneinfoga
      restart: on-failure
      image: sundowndev/phoneinfoga:latest
      command:
        - "serve"
      ports:
        - "80:5000"
```

--------------------------------

### Launch PhoneInfoga Web Server

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Start the PhoneInfoga web server, which includes a REST API and a web client. By default, it uses port 5000. You can specify a different port using the `-p` option.

```shell
phoneinfoga serve
```

```shell
phoneinfoga serve -p 8080
```

--------------------------------

### Google Dork Examples for Phone Number Search

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/resources/additional-resources.md

These Google dork examples can be used to search for phone numbers and related information across different websites and document types. They are useful for OSINT investigations.

```text
insubject:"+XXXXXXXXX" OR insubject:"+XXXXX" OR insubject:"XXXXX XXX XXX"
```

```text
insubject:"XXXXXXXXX" OR intitle:"XXXXXXXXX"
```

```text
intext:"XXXXXXXXX" AND (ext:doc OR ext:docx OR ext:odt OR ext:pdf OR ext:rtf OR ext:sxw OR ext:psw OR ext:ppt OR ext:pptx OR ext:pps OR ext:csv OR ext:txt OR ext:html)
```

```text
site:"hs3x.com" "+XXXXXXXXX"
```

```text
site:signal-arnaques.com intext:"XXXXXXXXX" intitle:" | Phone Fraud"
```

--------------------------------

### Local Scan Formatting - France Example

Source: https://github.com/sundowndev/phoneinfoga/wiki/Formatting

Structured output from a local scan for a French phone number, showing extracted components including input, default, local, international, country, and carrier details.

```python
{
    'input': '+33 0666519669',
    'default': '33666519669',
    'local': '666519669',
    'international': '+33 666519669',
    'country': 'France',
    'countryCode': '+33',
    'countryIsoCode': 'FR',
    'location': 'France',
    'carrier': 'Bouygues'
}
```

--------------------------------

### E.164 Formatting Example (UK)

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/resources/formatting.md

Illustrates the E.164 format for a UK-based phone number. Note the removal of the leading '0' typically used in local dialing.

```text
+442071838750
```

--------------------------------

### REST API: GET /api/v2/scanners

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Retrieve a list of all available scanners that can be used to scan phone numbers.

```APIDOC
## GET /api/v2/scanners

### Description
Retrieve a list of all available scanners that can be used to scan phone numbers.

### Method
GET

### Endpoint
/api/v2/scanners

### Response
#### Success Response (200)
- **scanners** (array) - A list of available scanners.
  - **name** (string) - The name of the scanner.
  - **description** (string) - A brief description of the scanner's function.

#### Response Example
```json
{
  "scanners": [
    {"name": "local", "description": "Gather offline info about a given phone number."},
    {"name": "numverify", "description": "Request info about a given phone number through the Numverify API."},
    {"name": "googlesearch", "description": "Generate several Google dork requests for a given phone number."},
    {"name": "googlecse", "description": "Googlecse searches for footprints of a given phone number on the web using Google Custom Search Engine."},
    {"name": "ovh", "description": "Search a phone number through the OVH Telecom REST API."}
  ]
}
```
```

--------------------------------

### Local Scan Formatting - US Example

Source: https://github.com/sundowndev/phoneinfoga/wiki/Formatting

Structured output from a local scan for a US phone number, detailing various extracted components like input, default, local, international, country, and carrier information.

```python
{
    'input': '+1 512-618-1212',
    'default': '15126181212',
    'local': '5126181212',
    'international': '+1 512-618-1212',
    'country': 'United States',
    'countryCode': '+1',
    'countryIsoCode': 'US',
    'location': 'Texas',
    'carrier': ''
}
```

--------------------------------

### Custom Formatting Examples for US Phone Numbers

Source: https://github.com/sundowndev/phoneinfoga/wiki/Formatting

Various custom formats for US-based phone numbers that can be used to improve search results. These mimic common online representations.

```text
+1 618-555-121
```

```text
(+1)618-555-121
```

```text
+1/618-555-121
```

```text
(618) 5551212
```

```text
(618) 555-1212
```

```text
(618) 555.1212
```

```text
(618)5551212
```

```text
(618)555-1212
```

```text
(618)555.1212
```

--------------------------------

### E.164 Formatting Example (US)

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/resources/formatting.md

Demonstrates the E.164 format for a US-based phone number. This format includes a plus sign, country code, area code, and local number.

```text
+14155552671
```

--------------------------------

### Custom Formatting Examples for French Phone Numbers

Source: https://github.com/sundowndev/phoneinfoga/wiki/Formatting

Various custom formats for French phone numbers, reflecting common online usage patterns. These can aid in more comprehensive searches.

```text
+3301 86 48 14 07
```

```text
+330186481407
```

```text
+33018 648 140 7
```

```text
(0033)0186481407
```

```text
(+33)018 648 140 7
```

```text
+33/0186481407
```

```text
(0033)018 648 140 7
```

```text
+33018-648-140-7
```

```text
(+33)0186481407
```

```text
(+33)01 86 48 14 07
```

```text
+33/018-648-140-7
```

```text
+33/01-86-48-14-07
```

```text
+3301-86-48-14-07
```

```text
(0033)01 86 48 14 07
```

```text
+33/01 86 48 14 07
```

```text
(+33)018-648-140-7
```

```text
(+33)01-86-48-14-07
```

```text
(0033)01-86-48-14-07
```

```text
(0033)018-648-140-7
```

```text
+33/018 648 140 7
```

--------------------------------

### PhoneInfoga REST API List Scanners

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Retrieve a list of all available scanners that can be used for phone number analysis via this GET endpoint. The response includes the name and description of each scanner.

```bash
curl -X GET "http://localhost:5000/api/v2/scanners"
```

```json
{
  "scanners": [
    {"name": "local", "description": "Gather offline info about a given phone number."},
    {"name": "numverify", "description": "Request info about a given phone number through the Numverify API."},
    {"name": "googlesearch", "description": "Generate several Google dork requests for a given phone number."},
    {"name": "googlecse", "description": "Googlecse searches for footprints of a given phone number on the web using Google Custom Search Engine."},
    {"name": "ovh", "description": "Search a phone number through the OVH Telecom REST API."}
  ]
}
```

--------------------------------

### Test OVH Scanner Availability - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Perform a dry run for the OVH scanner to check country code support. This example shows a failure for an unsupported country code.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/ovh/dryrun" \
  -H "Content-Type: application/json" \
  -d '{"number": "+15554441212", "options": {}}'
```

--------------------------------

### PhoneInfoga REST API Health Check

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Use this GET endpoint to check if the API service is healthy and retrieve version information. Assumes the server is running on the default port 5000.

```bash
curl -X GET "http://localhost:5000/api/"
```

```json
{
  "success": true,
  "version": "v2.x.x",
  "commit": "abc123",
  "demo": false
}
```

--------------------------------

### Google Dork Examples for Phone Number Footprinting

Source: https://github.com/sundowndev/phoneinfoga/wiki/Resources

These Google dorks can be used to find specific phone number formats, document types associated with numbers, or information on specific websites. Adjust the 'XXXXXXXXX' placeholders with actual phone number patterns or keywords.

```google-dork
insubject:"+XXXXXXXXX" | insubject:"+XXXXX" | insubject:"XXXXX XXX XXX"
```

```google-dork
insubject:"XXXXXXXXX" | intitle:"XXXXXXXXX"
```

```google-dork
intext:"XXXXXXXXX" ext:doc | ext:docx | ext:odt | ext:pdf | ext:rtf | ext:sxw | ext:psw | ext:ppt | ext:pptx | ext:pps | ext:csv | ext:txt | ext:html
```

```google-dork
site:"hs3x.com" intext:"+XXXXXXXXX"
```

```google-dork
site:signal-arnaques.com intext:"XXXXXXXXX" intitle: | Phone Fraud
```

--------------------------------

### Serve MkDocs Documentation

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Serves the documentation website locally on localhost, allowing for live preview during development.

```shell
mkdocs serve
# or
python3 -m mkdocs serve
```

--------------------------------

### CLI Command: serve

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Launches a web server that provides both a REST API and an optional Vue.js web client for browser-based scanning.

```APIDOC
## CLI Command: serve

### Description
Launches a web server that provides both a REST API and an optional Vue.js web client for browser-based scanning.

### Usage
```bash
phoneinfoga serve
phoneinfoga serve -p 8080
phoneinfoga serve --no-client
phoneinfoga serve -p 8080 --env-file=.env.local -D ovh

# Docker usage
docker run --rm -it -p 5000:5000 sundowndev/phoneinfoga serve
docker run --rm -it -p 8080:8080 sundowndev/phoneinfoga serve -p 8080 --no-client
```

### Parameters
#### Query Parameters
- **-p, --port** (integer) - Optional - The port to run the server on. Defaults to 5000.
- **--no-client** (boolean) - Optional - Disable the web client, serving only the REST API.
- **--env-file** (string) - Optional - Path to a custom environment file.
- **-D, --disable** (string) - Optional - Disable a specific scanner (can be used multiple times).

### Docker Compose Example
```yaml
version: '3.7'
services:
    phoneinfoga:
      container_name: phoneinfoga
      restart: on-failure
      image: sundowndev/phoneinfoga:latest
      command:
        - "serve"
        - "--no-client"
      ports:
        - "80:5000"
      environment:
        - NUMVERIFY_API_KEY=your_key
        - GOOGLECSE_CX=your_search_engine_id
        - GOOGLE_API_KEY=your_google_api_key
```
```

--------------------------------

### Build for Production

Source: https://github.com/sundowndev/phoneinfoga/blob/master/web/client/README.md

Compiles and minifies the application for production deployment. This command prepares the optimized build artifacts.

```bash
yarn build
```

--------------------------------

### Run Application with Go

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Compiles and runs the application using `go run`. This is useful for development as it avoids the need to rebuild for every change.

```shell
$ go run main.go
```

--------------------------------

### Deploy MkDocs to GitHub Pages

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Deploys the built documentation website to GitHub Pages.

```shell
mkdocs gh-deploy
```

--------------------------------

### Open Go Coverage File

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Opens the generated coverage file in an HTML format for review.

```shell
# Open coverage file as HTML
go tool cover -html=coverage.out
```

--------------------------------

### Build MkDocs Website

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Builds the static HTML files for the documentation website.

```shell
mkdocs build
```

--------------------------------

### Build Project with In-Memory Assets

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Generates in-memory assets and then builds the project. This step is required for building and places the contents of the dist directory into a single binary file. It needs to be performed after each client-side change during development.

```shell
# Generate in-memory assets, then build the project.
# This will put content of dist directory in a single binary file.
# It's needed to build but the design requires you to do it anyway.
# This step is needed at each change if you're developing on the client.
$ make build
```

--------------------------------

### Build Static Assets

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Builds the static assets for the web client. This command should be run within the web/client directory.

```shell
# Build static assets
# This will create dist directory containing client's static files
$ (cd web/client && yarn && yarn build)
```

--------------------------------

### Create Scanner Library with Filter

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Use `remote.NewLibrary` to create a scanner manager. Filters can disable specific scanners, and scanners can be added individually or loaded as plugins. Options are passed during the scan execution.

```go
package main

import (
	"fmt"
	"log"

	"github.com/sundowndev/phoneinfoga/v2/lib/filter"
	"github.com/sundowndev/phoneinfoga/v2/lib/number"
	"github.com/sundowndev/phoneinfoga/v2/lib/remote"
)

func main() {
	// Parse the target phone number
	n, err := number.NewNumber("+15554441212")
	if err != nil {
		log.Fatal(err)
	}

	// Create a filter to optionally disable specific scanners
	f := filter.NewEngine()
	f.AddRule("numverify") // Disable numverify scanner

	// Create scanner library with filter
	lib := remote.NewLibrary(f)

	// Add individual scanners
	lib.AddScanner(remote.NewLocalScanner())
	lib.AddScanner(remote.NewGoogleSearchScanner())

	// Or load all registered plugins
	lib.LoadPlugins()

	// Execute all scanners with options
	opts := remote.ScannerOptions{
		"NUMVERIFY_API_KEY": "your_api_key",
		"GOOGLECSE_CX":      "your_search_engine_id",
		"GOOGLE_API_KEY":    "your_google_api_key",
	}
	results, errors := lib.Scan(n, opts)

	// Process results
	for scannerName, result := range results {
		fmt.Printf("Results from %s: %+v\n", scannerName, result)
	}

	// Handle errors
	for scannerName, err := range errors {
		fmt.Printf("Error from %s: %v\n", scannerName, err)
	}
}
```

--------------------------------

### Set Environment Variables for PhoneInfoga

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Configure API keys and settings using an environment file for PhoneInfoga.

```bash
NUMVERIFY_API_KEY=your_numverify_api_key

GOOGLECSE_CX=your_search_engine_id
GOOGLE_API_KEY=your_google_api_key
GOOGLECSE_MAX_RESULTS=20  # Optional: max 100, default 10
```

--------------------------------

### Launch PhoneInfoga Web Server via Docker

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Run the PhoneInfoga web server using Docker, mapping the container port to the host port. This allows for easy deployment and management.

```shell
docker run --rm -it -p 5000:5000 sundowndev/phoneinfoga serve
```

```shell
docker run --rm -it -p 8080:8080 sundowndev/phoneinfoga serve -p 8080
```

--------------------------------

### Run Go Test Suite

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Executes the test suite for the Go code. The `-v` flag provides verbose output.

```shell
# Run test suite
go test -v ./...
```

--------------------------------

### Build a Go Plugin for Phoneinfoga

Source: https://github.com/sundowndev/phoneinfoga/blob/master/examples/plugin/README.md

Use this command to build a Go source file into a shared library plugin for Phoneinfoga. Ensure you are in the directory containing your custom scanner code.

```shell
$ go build -buildmode=plugin ./customscanner.go
```

--------------------------------

### Launch REST API Only

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Run the PhoneInfoga web server with only the REST API enabled, disabling the web client using the `--no-client` flag.

```shell
phoneinfoga serve --no-client
```

--------------------------------

### Run Unit Tests

Source: https://github.com/sundowndev/phoneinfoga/blob/master/web/client/README.md

Executes the unit tests for the project. Ensure all unit tests pass before proceeding with further development or deployment.

```bash
yarn test:unit
```

--------------------------------

### Build PhoneInfoga Docker Image

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Builds the PhoneInfoga Docker image from the source code using docker-compose.

```shell
docker-compose build
```

--------------------------------

### Run PhoneInfoga Scan with Custom Plugin

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Execute a PhoneInfoga scan using a custom scanner plugin. Plugins must be written in the Go programming language.

```shell
$ phoneinfoga scan -n +4176418xxxx --plugin ./custom_scanner.so
```

--------------------------------

### Run GoogleCSE Scanner - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute the Google Custom Search Engine (CSE) scanner. Requires GOOGLECSE_CX and GOOGLE_API_KEY in options.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/googlecse/run" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+1241325xxxx",
    "options": {
      "GOOGLECSE_CX": "your_search_engine_id",
      "GOOGLE_API_KEY": "your_google_api_key"
    }
  }'
```

--------------------------------

### Run Local Scanner - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute the local scanner against a phone number. No authentication is required for this scanner.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/local/run" \
  -H "Content-Type: application/json" \
  -d '{"number": "+15554441212", "options": {}}'
```

--------------------------------

### Create Custom Scanner Plugin

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Develop custom scanners by implementing the `remote.Scanner` interface. Plugins are built as shared libraries (`.so`) and registered using `remote.RegisterPlugin`. Ensure the `DryRun` method validates prerequisites like API keys or country support.

```go
// customscanner.go - Build with: go build -buildmode=plugin -o customscanner.so customscanner.go
package main

import (
	"github.com/sundowndev/phoneinfoga/v2/lib/number"
	"github.com/sundowndev/phoneinfoga/v2/lib/remote"
)

type customScanner struct{}

type customScannerResponse struct {
	Valid  bool   `json:"valid" console:"Valid"`
	Info   string `json:"info" console:"Info"`
	Hidden string `json:"-" console:"-"` // Won't appear in output
}

// Name returns the unique scanner identifier
func (s *customScanner) Name() string {
	return "customscanner"
}

// Description returns a human-readable description
func (s *customScanner) Description() string {
	return "Custom scanner for specialized phone number lookups"
}

// DryRun validates if this scanner can run for the given number
// Return an error to skip this scanner
func (s *customScanner) DryRun(n number.Number, opts remote.ScannerOptions) error {
	// Check for required API key
	if opts.GetStringEnv("CUSTOM_API_KEY") == ""
		return fmt.Errorf("CUSTOM_API_KEY is required")
	}
	// Check for country support
	if n.CountryCode != 1 {
		return fmt.Errorf("only US numbers supported")
	}
	return nil
}

// Run executes the actual scan (runs in a goroutine)
func (s *customScanner) Run(n number.Number, opts remote.ScannerOptions) (interface{}, error) {
	apiKey := opts.GetStringEnv("CUSTOM_API_KEY")

	// Perform your custom lookup logic here
	// ...

	return customScannerResponse{
		Valid:  true,
		Info:   fmt.Sprintf("Custom data for %s", n.E164),
		Hidden: "internal data",
	},
	nil
}

// Register the plugin on package initialization
func init() {
	remote.RegisterPlugin(&customScanner{})
}

// Usage: phoneinfoga scan -n "+15554441212" --plugin ./customscanner.so

```

--------------------------------

### Configure Environment Variables for Scanners

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Set API keys and other configuration values using environment variables. These can be defined inline or in a .env file. The tool automatically parses .env files.

```shell
# .env.local
NUMVERIFY_API_KEY="value"
GOOGLECSE_CX="value"
GOOGLE_API_KEY="value"
```

```shell
phoneinfoga scan -n +4176418xxxx --env-file=.env.local
```

--------------------------------

### Run Numverify Scanner - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute the Numverify scanner against a phone number. Requires a NUMVERIFY_API_KEY to be provided in the options.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/numverify/run" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+4176418xxxx",
    "options": {
      "NUMVERIFY_API_KEY": "your_api_key"
    }
  }'
```

--------------------------------

### Launch REST API Only via Docker

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Run the PhoneInfoga REST API only using Docker, disabling the web client with the `--no-client` flag and mapping the ports.

```shell
docker run --rm -it -p 5000:5000 sundowndev/phoneinfoga serve --no-client
```

--------------------------------

### Run PhoneInfoga in Docker

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Executes the PhoneInfoga tool within a Docker container to check its version.

```shell
docker run --rm -it sundowndev/phoneinfoga version
```

--------------------------------

### Collect Go Test Coverage

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Generates a coverage profile for the Go tests.

```shell
# Collect coverage
go test -coverprofile=coverage.out ./&&
```

--------------------------------

### Run PhoneInfoga CLI via Docker Compose

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Executes the PhoneInfoga command-line interface within a Docker Compose environment.

```shell
docker-compose run --rm phoneinfoga --help
```

--------------------------------

### Run GoogleSearch Scanner - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute the GoogleSearch scanner against a phone number. This scanner performs a Google search for the number.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/googlesearch/run" \
  -H "Content-Type: application/json" \
  -d '{"number": "+4176418xxxx", "options": {}}'
```

--------------------------------

### Format Go Code

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Formats Go files using `gofmt`.

```shell
make fmt
```

--------------------------------

### POST /api/v2/scanners/{scanner}/run - Run a Specific Scanner

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute a single scanner against a phone number with optional configuration options that override environment variables.

```APIDOC
## POST /api/v2/scanners/{scanner}/run

### Description
Execute a single scanner against a phone number with optional configuration options that override environment variables.

### Method
POST

### Endpoint
/api/v2/scanners/{scanner}/run

### Parameters
#### Path Parameters
- **scanner** (string) - Required - The name of the scanner to run (e.g., 'local', 'numverify', 'googlesearch', 'googlecse', 'ovh').

#### Request Body
- **number** (string) - Required - The phone number to scan (e.g., '+15554441212').
- **options** (object) - Optional - A key-value map of options to override environment variables for the scanner.

### Request Example
```json
{
  "number": "+15554441212",
  "options": {}
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the scanner execution. The structure varies depending on the scanner used.

#### Response Example (local scanner)
```json
{
  "result": {
    "raw_local": "5554441212",
    "local": "(555) 444-1212",
    "e164": "+15554441212",
    "international": "15554441212",
    "country_code": 1,
    "country": "US"
  }
}
```

#### Response Example (numverify scanner)
```json
{
  "result": {
    "valid": true,
    "number": "4176418xxxx",
    "local_format": "076418xxxx",
    "international_format": "+4176418xxxx",
    "country_prefix": "+41",
    "country_code": "CH",
    "country_name": "Switzerland (Confederation of)",
    "carrier": "Sunrise Communications AG",
    "line_type": "mobile"
  }
}
```
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/sundowndev/phoneinfoga/blob/master/web/client/README.md

Executes the end-to-end tests for the project. These tests simulate user interactions to ensure the application functions correctly.

```bash
yarn test:e2e
```

--------------------------------

### Inspect Docker Container Logs

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Retrieves logs from a running PhoneInfoga Docker container for troubleshooting.

```shell
docker logs -f <container-id|container-name>
```

--------------------------------

### Scan Phone Number with Inline Environment Variables

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute a phone number scan by providing environment variables directly on the command line.

```bash
NUMVERIFY_API_KEY=key GOOGLECSE_CX=cx GOOGLE_API_KEY=key phoneinfoga scan -n "+15554441212"
```

--------------------------------

### Run TypeScript Tests

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Executes tests for the TypeScript code within the web client. Navigate to the `web/client` directory before running these commands.

```shell
cd web/client

yarn test
yarn test:unit
yarn test:e2e
```

--------------------------------

### Use a Custom Plugin with Phoneinfoga

Source: https://github.com/sundowndev/phoneinfoga/blob/master/examples/plugin/README.md

Scan a phone number using a custom plugin by specifying its path with the --plugin flag. The --plugin flag can be used multiple times to load several plugins.

```shell
$ phoneinfoga scan -n <number> --plugin ./customscanner.so

Running scan for phone number <number>...

Results for customscanner
Valid: true
Info: This number is known for scams!

...
```

--------------------------------

### Lint and Fix Files

Source: https://github.com/sundowndev/phoneinfoga/blob/master/web/client/README.md

Lints the project files and automatically fixes any style or formatting issues according to the project's linting rules.

```bash
yarn lint
```

--------------------------------

### Run OVH Scanner - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Execute the OVH scanner against a phone number. This scanner supports EU country codes and does not require authentication.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/ovh/run" \
  -H "Content-Type: application/json" \
  -d '{"number": "+3336517xxxx", "options": {}}'
```

--------------------------------

### Pull PhoneInfoga Docker Image

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Pulls the latest stable version of the PhoneInfoga Docker image from Docker Hub.

```shell
docker pull sundowndev/phoneinfoga:latest
```

--------------------------------

### Scan Phone Number with .env File

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Perform a phone number scan using environment variables loaded from a .env file.

```bash
phoneinfoga scan -n "+15554441212" --env-file=.env.production
```

--------------------------------

### Numverify Scanner with API Key

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Scan a phone number using the Numverify service. This requires a NUMVERIFY_API_KEY, which can be set as an environment variable. The output includes validation status, number details, and carrier information.

```shell
$ NUMVERIFY_API_KEY=<key> phoneinfoga scan -n +4176418xxxx

Results for numverify
Valid: true
Number: 4176418xxxx
Local format: 076418xxxx
International format: +4176418xxxx
Country prefix: +41
Country code: CH
Country name: Switzerland (Confederation of)
Carrier: Sunrise Communications AG
Line type: mobile
```

--------------------------------

### Generate Google Search Dork URLs

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

The `remote.NewGoogleSearchScanner` creates a scanner that generates Google dork URLs for various search categories. Ensure the phone number is parsed correctly before running.

```go
package main

import (
	"fmt"
	"log"

	"github.com/sundowndev/phoneinfoga/v2/lib/number"
	"github.com/sundowndev/phoneinfoga/v2/lib/remote"
)

func main() {
	n, err := number.NewNumber("+4176418xxxx")
	if err != nil {
		log.Fatal(err)
	}

	// Create Google Search scanner
	scanner := remote.NewGoogleSearchScanner()

	// Run the scanner
	result, err := scanner.Run(*n, remote.ScannerOptions{})
	if err != nil {
		log.Fatal(err)
	}

	// Cast result to GoogleSearchResponse
	res := result.(remote.GoogleSearchResponse)

	// Access social media dork URLs
	fmt.Println("Social Media Search URLs:")
	for _, dork := range res.SocialMedia {
		fmt.Printf("  %s\n", dork.URL)
	}

	// Access reputation dork URLs
	fmt.Println("\nReputation Search URLs:")
	for _, dork := range res.Reputation {
		fmt.Printf("  %s\n", dork.URL)
	}

	// Access individual search dork URLs
	fmt.Println("\nIndividual Search URLs:")
	for _, dork := range res.Individuals {
		fmt.Printf("  %s\n", dork.URL)
	}

	// Access disposable provider dork URLs
	fmt.Println("\nDisposable Provider URLs:")
	for _, dork := range res.DisposableProviders {
		fmt.Printf("  %s\n", dork.URL)
	}

	// Access general dork URLs
	fmt.Println("\nGeneral Search URLs:")
	for _, dork := range res.General {
		fmt.Printf("  %s\n", dork.URL)
	}
}
```

--------------------------------

### Test Numverify Scanner Availability - Phoneinfoga API

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Perform a dry run for the Numverify scanner to test configuration and authentication. Requires NUMVERIFY_API_KEY.

```bash
curl -X POST "http://localhost:5000/api/v2/scanners/numverify/dryrun" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+15554441212",
    "options": {
      "NUMVERIFY_API_KEY": "your_api_key"
    }
  }'
```

--------------------------------

### Scan Multiple Numbers and Output to File

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Scan multiple phone numbers from an input file and save the results to an output file. Invalid numbers in the input file will be skipped.

```shell
phoneinfoga scan -i numbers.txt -o results.txt
```

--------------------------------

### Scan Phone Number with PhoneInfoga CLI

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Use the 'scan' command to perform phone number analysis. Supports E164 or international formats. API keys can be provided via environment variables or custom files.

```bash
# Basic scan with international format
phoneinfoga scan -n "+1 555-444-1212"
```

```bash
# Scan with country code (essential for proper parsing)
phoneinfoga scan -n "+33 06 79368229"
```

```bash
# Scan with raw number format
phoneinfoga scan -n "33679368229"
```

```bash
# Scan with environment variables for authenticated scanners
NUMVERIFY_API_KEY=your_key phoneinfoga scan -n "+4176418xxxx"
```

```bash
# Scan with custom environment file
phoneinfoga scan -n "+4176418xxxx" --env-file=.env.local
```

```bash
# Scan with specific scanners disabled
phoneinfoga scan -n "+1 555-444-1212" -D numverify -D ovh
```

```bash
# Scan with custom plugin
phoneinfoga scan -n "+4176418xxxx" --plugin ./custom_scanner.so
```

```bash
# Expected output:
# Running scan for phone number +1 555-444-1212...
#
# Results for local
# Raw local: 5554441212
# Local: (555) 444-1212
# E164: +15554441212
# International: 15554441212
# Country: US
#
# Results for googlesearch
# Social media:
#     URL: https://www.google.com/search?q=site%3Afacebook.com+intext%3A%2215554441212%22...
```

--------------------------------

### Disable Web Client in Docker Compose

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/install.md

Modifies the docker-compose.yml file to disable the web client when running PhoneInfoga.

```yaml
# docker-compose.yml
command:
  - "serve"
  - "--no-client"
```

--------------------------------

### Footprinting a Phone Number

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Perform footprinting for a given phone number using the `-s footprints` option.

```shell
phoneinfoga scan -n +42837544833 -s footprints
```

--------------------------------

### Go Module API - number.NewNumber

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

Parse and validate a phone number string, returning a structured Number object with various format representations.

```APIDOC
## Go Module API

### number.NewNumber

### Description
Parse and validate a phone number string, returning a structured Number object with various format representations.

### Usage
```go
import "github.com/sundowndev/phoneinfoga/v2/lib/number"

// Parse a phone number
n, err := number.NewNumber("+15554441212")
if err != nil {
    // Handle error
}

// Access parsed number information
fmt.Printf("Valid: %v\n", n.Valid)
fmt.Printf("E164: %s\n", n.E164)
fmt.Printf("International: %s\n", n.International)
fmt.Printf("Local: %s\n", n.Local)
fmt.Printf("RawLocal: %s\n", n.RawLocal)
fmt.Printf("Country: %s\n", n.Country)
fmt.Printf("CountryCode: %d\n", n.CountryCode)
fmt.Printf("Carrier: %s\n", n.Carrier)
```

### Parameters
- **phoneNumber** (string) - The phone number string to parse. Supports E.164 and international formats.

### Returns
- **(*number.Number, error)** - A pointer to a Number object containing parsed details and an error if parsing fails.
```

--------------------------------

### Custom Format Reconnaissance

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/usage.md

Utilize the `recon` command to automatically try several custom formats based on the country code for reconnaissance.

```shell
phoneinfoga recon -n +42837544833
```

--------------------------------

### Googlesearch Reputation Links

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/getting-started/scanners.md

Generated Google search URLs for checking phone number reputation and scam reports. These links are for manual inspection.

```shell
URL: https://www.google.com/search?q=site%3Awhosenumber.info+intext%3A%22%2B4176418xxxx%22+intitle%3A%22who+called%22
```

```shell
URL: https://www.google.com/search?q=intitle%3A%22Phone+Fraud%22+intext%3A%224176418xxxx%22+OR+intext%3A%22%2B4176418xxxx%22+OR+intext%3A%22076418xxxx%22
```

--------------------------------

### CLI Command: scan

Source: https://context7.com/sundowndev/phoneinfoga/llms.txt

The `scan` command performs phone number analysis using all configured scanners. It accepts phone numbers in E164 or international format and outputs detailed information.

```APIDOC
## CLI Command: scan

### Description
Performs phone number analysis using all configured scanners. Accepts phone numbers in E164 or international format and outputs detailed information including carrier, country, and OSINT footprints.

### Usage
```bash
phoneinfoga scan -n "+1 555-444-1212"
phoneinfoga scan -n "+33 06 79368229"
phoneinfoga scan -n "33679368229"
NUMVERIFY_API_KEY=your_key phoneinfoga scan -n "+4176418xxxx"
phoneinfoga scan -n "+4176418xxxx" --env-file=.env.local
phoneinfoga scan -n "+1 555-444-1212" -D numverify -D ovh
phoneinfoga scan -n "+4176418xxxx" --plugin ./custom_scanner.so
```

### Parameters
#### Query Parameters
- **-n, --number** (string) - Required - The phone number to scan (E.164 or international format).
- **-D, --disable** (string) - Optional - Disable a specific scanner (can be used multiple times).
- **--env-file** (string) - Optional - Path to a custom environment file.
- **--plugin** (string) - Optional - Path to a custom scanner plugin.

### Expected Output Example
```
Running scan for phone number +1 555-444-1212...

Results for local
Raw local: 5554441212
Local: (555) 444-1212
E164: +15554441212
International: 15554441212
Country: US

Results for googlesearch
Social media:
    URL: https://www.google.com/search?q=site%3Afacebook.com+intext%3A%2215554441212%22...
```
```

--------------------------------

### Lint and Fix TypeScript Code

Source: https://github.com/sundowndev/phoneinfoga/blob/master/docs/contribute.md

Lints and attempts to fix formatting issues in TypeScript code. Navigate to the `web/client` directory before running these commands.

```shell
cd web/client

yarn lint
yarn lint:fix
```
Tokens:
Raw