Advanced Search - OWASP Nest

OWASP Nest provides powerful structured search capabilities with advanced query syntax and filtering. This guide covers all available search features and operators.

Search Query Syntax

Nest uses a structured query parser that supports field-specific searches, comparison operators, and quoted strings.

Basic Field Syntax

Search specific fields using the field:value format:

name:nest
stars:100
language:python

Field Types

The query parser supports four field types:

String Fields

Text-based searches with partial matchingExample: name:nest language:python

Number Fields

Numeric searches with comparison operatorsExample: stars:100 forks>50

Boolean Fields

True/false valuesExample: archived:false is_template:true

Date Fields

Date-based searches with comparisonsExample: created_at>2024-01-01

Comparison Operators

Use comparison operators with number and date fields:

Operator	Description	Example
`=`	Equal to (default)	`stars=100`
`>`	Greater than	`stars>100`
`<`	Less than	`stars<100`
`>=`	Greater than or equal	`stars>=100`
`<=`	Less than or equal	`stars<=100`

Number Field Examples

# Repositories with exactly 100 stars
stars:100
stars=100

# Repositories with more than 100 stars
stars>100

# Repositories with 50 or fewer stars
stars<=50

# Contributors count greater than or equal to 10
contributors>=10

Date Field Examples

# Created after January 1, 2024
created_at>2024-01-01
created_at>20240101

# Updated before December 31, 2023
updated_at<2023-12-31

# Created on specific date
created_at=2024-01-15

Date formats supported: YYYY-MM-DD or YYYYMMDD

String Matching

String fields support two matching strategies:

Case-Insensitive Partial Match (Default)

# Matches "Nest", "nest", "OWASP Nest", etc.
name:nest

# Matches "Python", "python", "python3", etc.
language:python

Exact Match

Use quotes for exact matching:

# Exact match (case-sensitive in strict mode)
name:"OWASP Nest"

language:"TypeScript"

Quoted Strings

Use double quotes for multi-word values:

# Search for projects with spaces in the name
name:"Web Security Testing Guide"

# Search for multi-word descriptions
description:"application security"

Escaping Quotes

Escape quotes within quoted strings:

name:"OWASP \"Nest\" Project"

Boolean Values

Boolean fields accept multiple value formats: True values: true, 1, yes, on False values: false, 0, no, off

# All equivalent searches for archived repositories
archived:true
archived:1
archived:yes
archived:on

# All equivalent searches for non-archived repositories
archived:false
archived:0
archived:no
archived:off

Combining Conditions

All conditions are combined with implicit AND logic:

# Repositories named "nest" with more than 100 stars
name:nest stars>100

# Python projects with over 50 forks, updated this year
language:python forks>50 updated_at>2024-01-01

# Active (non-archived) projects with high engagement
archived:false stars>500 contributors>10

OR logic is not supported. All conditions must match.

Free-Text Search

Tokens without a field prefix are treated as free-text searches:

# Searches default field (typically "query" or "name")
security testing

# Mix structured and free-text
web security language:javascript

Real-World Examples

Find Popular Python Projects

language:python stars>100 forks>20 archived:false

Find Recently Updated Projects

updated_at>2024-01-01 stars>50

Find Beginner-Friendly Projects

stars>10 stars<100 contributors>3

Find Projects by Technology

language:typescript name:nest updated_at>2023-01-01

Searchable Fields by Entity

Repositories

name

string

Repository name (partial match)

language

string

Primary programming language

stars

number

Number of GitHub stars

forks

number

Number of repository forks

contributors

number

Number of unique contributors

archived

boolean

Whether the repository is archived

created_at

date

Repository creation date

updated_at

date

Last update date

Projects

name

string

Project name (partial match)

level

string

Project level (e.g., “flagship”, “lab”)

created_at

date

Project creation date

updated_at

date

Last update date

Chapters

name

string

Chapter name (partial match)

country

string

Chapter country

region

string

Geographic region

Error Handling

The query parser gracefully handles errors:

Unknown Fields

# Unknown field is ignored (non-strict mode)
invalidfield:value name:nest
# Result: Only searches by name:nest

Invalid Values

# Invalid number format is ignored
stars:abc name:nest
# Result: Only searches by name:nest

Malformed Dates

# Invalid date format is ignored
created_at:2024-13-01 name:nest
# Result: Only searches by name:nest

In non-strict mode, invalid conditions are silently ignored. Your search will still work with valid conditions.

Implementation Details

Nest’s structured search is powered by a custom query parser:

Parser Configuration

from apps.common.search.query_parser import QueryParser

# Define searchable fields
field_schema = {
    "name": "string",
    "stars": "number",
    "archived": "boolean",
    "created_at": "date"
}

# Initialize parser
parser = QueryParser(
    field_schema=field_schema,
    case_sensitive=False,
    default_field="query",
    strict=False
)

# Parse query
conditions = parser.parse("name:nest stars>100")

Query Result Format

[
    {
        "field": "name",
        "type": "string",
        "value": "nest"
    },
    {
        "field": "stars",
        "type": "number",
        "op": ">",
        "value": 100
    }
]

API Integration

Use structured search with the REST API:

Search Repositories

curl "https://nest.owasp.org/api/v0/repositories/?q=language:python+stars>100"

Search Projects

curl "https://nest.owasp.org/api/v0/projects/?q=level:flagship+updated_at>2024-01-01"

URL Encoding

Remember to URL-encode special characters:

# Raw query
language:python stars>100

# URL encoded
language%3Apython+stars%3E100

cURL
Python
JavaScript

curl -G "https://nest.owasp.org/api/v0/repositories/" \
  --data-urlencode "q=language:python stars>100"

import requests
from urllib.parse import urlencode

params = {"q": "language:python stars>100"}
url = f"https://nest.owasp.org/api/v0/repositories/?{urlencode(params)}"
response = requests.get(url)

const params = new URLSearchParams({
  q: 'language:python stars>100'
});

const response = await fetch(
  `https://nest.owasp.org/api/v0/repositories/?${params}`
);

Best Practices

Start Simple

Begin with basic searches and add conditions incrementally:

name:nest
name:nest stars>100
name:nest stars>100 language:python

Use Appropriate Operators

Choose operators that match your intent:

Use > for “at least” searches: stars>100
Use >= for “minimum” thresholds: contributors>=10
Use < for “maximum” limits: forks<50

Quote Multi-Word Values

Always quote strings with spaces:

# Correct
name:"Web Application Firewall"

# Incorrect (will split into multiple tokens)
name:Web Application Firewall

Validate Date Formats

Use ISO format dates for clarity:

# Preferred
created_at>2024-01-01

# Also valid
created_at>20240101

Test your search queries in the API before integrating them into applications!

Get Started

Platform Features

User Guides

Development

Deployment

​Search Query Syntax

​Basic Field Syntax

​Field Types

String Fields

Number Fields

Boolean Fields

Date Fields

​Comparison Operators

​Number Field Examples

​Date Field Examples

​String Matching

​Case-Insensitive Partial Match (Default)

​Exact Match

​Quoted Strings

​Escaping Quotes

​Boolean Values

​Combining Conditions

​Free-Text Search

​Real-World Examples

​Find Popular Python Projects

​Find Recently Updated Projects

​Find Beginner-Friendly Projects

​Find Projects by Technology

​Searchable Fields by Entity

​Repositories

​Projects

​Chapters

​Error Handling

​Unknown Fields

​Invalid Values

​Malformed Dates

​Implementation Details

​Parser Configuration

​Query Result Format

​API Integration

​Search Repositories

​Search Projects

​URL Encoding

​Best Practices

Build docs developers (and LLMs) love

Search Query Syntax

Basic Field Syntax

Field Types

Comparison Operators

Number Field Examples

Date Field Examples

String Matching

Case-Insensitive Partial Match (Default)

Exact Match

Quoted Strings

Escaping Quotes

Boolean Values

Combining Conditions

Free-Text Search

Real-World Examples

Find Popular Python Projects

Find Recently Updated Projects

Find Beginner-Friendly Projects

Find Projects by Technology

Searchable Fields by Entity

Repositories

Projects

Chapters

Error Handling

Unknown Fields

Invalid Values

Malformed Dates

Implementation Details

Parser Configuration

Query Result Format

API Integration

Search Repositories

Search Projects

URL Encoding

Best Practices