Allow API Fuzzing or DAST API to provide variables value using Postman environment file.
Problem
Postman GUI allows users to export a given environment to a JSON file. The Postman environment file contains a list of well-known variables defined by the user. On the other hand, a user of API security (DAST API or API Fuzzing) can provide values for the variables by using a JSON document, which is not compatible with the Postman environment file.
The problem is that the customer has to translate the Postman environment file to a JSON document compatible with API Security (DAST API or API Fuzzing), or manually provide the JSON file format when with a few clicks they can get an updated file from the Postman GUI.
Possible solution
Allow API Fuzzing or DAST API to consume the Postman environment file to provide variable values.
Remarks
- Postman GUI allows the user to export different files, all of them may contain variables.
-
Postman data
file, -
Postman environment
file, this file can be created by selectingEnvironments
, in the left tab, then selecting a previously created environment. Last, in the right side use the dots menu (...
) and selectExport
. Notice that there is also a special environment called:Global
is a fixed environment, which can be exported in a separate file. Postman data dumps
-
- Exported Postman file may not contain values for all variables:
- For example, Dynamic variables are not provided in exported environments.
- Another case is when a variable is set programmatically. The GUI or runners (e.g. Newman) creates the variable during collection execution.
- Variables have different scopes, and some of the variables are set as global (exported only in workspace) while other are exported in the environment.
- Data variables are not included in the
Postman environment
file.
- There is not much documentation about formats other than
Postman data Schema
Proposal
-
Enable FeatureFlag-
Add FeatureFlag service -
Add FlagName to this feature
-
-
Add support to new file format postman environmental file
.-
Detect and load postman environmental file. - a postman environmental file, where the JSON document is an object featuring properties:
-
_postman_variable_scope
set toenvironment
orglobal
. (Required) -
values
are set to an array. Each entry of the array is a JSON object, with at least the following properties:key
,value
,type
, andenabled
.
-
- a postman environmental file, where the JSON document is an object featuring properties:
-
Update/Add tests -
Add unit test using postman environmental file.
-
-
-
Support multiple files in _POSTMAN_COLLECTION_VARIABLES
-
Allow accepting multiple files in _POSTMAN_COLLECTION_VARIABLES
, file paths are comma-separated. Each file in_POSTMAN_COLLECTION_VARIABLES
can be:- a postman environmental file
- a flat JSON object, using key-value pairs. (This is the current implementation)
-
Update runner options -
to accept a list of files. -
to validate file is accessible -
to validate file format is correct (file can be either postman environmental file or flat JSON object)
-
-
Update postman reader to detect and load postman environmental files, otherwise treat file a flat JSON object. -
Update documentation in API Fuzzing and DAST API to: -
mention that _POSTMAN_COLLECTION_VARIABLES
supports multiple files. -
mention that a given entry in _POSTMAN_COLLECTION_VARIABLES
can be either a postman environmental file or a JSON flat object. -
mention that environmental files may or may not provide all variables, and environmental variable _POSTMAN_COLLECTION_VARIABLES_GENERATION
may produce values for non-user-defined variables. -
Remove the warning about using only flat JSON objects.Add note that after 15.0 there is support for Postman Environment format.
-
-
Add tests -
Add/Update Unit test providing none, a single, and multiple files. Mixing up two formats. -
Add unit test for new runner option validations: files exist, the file does not exist, the file has valid content, file has invalid content (empty, non-valid JSON, incomplete JSON).
-
-
-
Add support to scope variables -
Load and unload variables from each scope -
Global
: Values can be set thru GUI in environment tab, and they cab be Loaded from files provided in_POSTMAN_COLLECTION_VARIABLES
. The file must be a JSON document with a JSON object with a property_postman_variable_scope
set toglobals
-
Collection
: Values can be set thru GUI in Collection details, and they cab be Loaded from the file provided in_POSTMAN_COLLECTION
. Variables are taken from array node at$.variable
. -
Environment
: Values can be set thru GUI in environment tab, and they cab be Loaded from files provided in_POSTMAN_COLLECTION_VARIABLES
. The file must be a JSON document with a JSON object with a property_postman_variable_scope
set toenvironment
-
Json
: Values loaded from KeyValur Pairs from JSON document. NOTE This is not a postman scope, but it is defined to support the old variable file format. - [-]
Data
: This will not be implemented. - [-]
Local
: Value seem to be set only in scripts in GUI. Postman schema defines variables for folders and items (requests). It seems UI does not provide a mechanism to edit them, and documentation does not specify their scope either. TDB Since they are in a hierarchy structure, they can be treat asLocal
and loaded and unloaded based on the hierarchy.- [-]
Load from the file provided in_POSTMAN_COLLECTION
. Variables are taken from array node at$.item[*].variable
.- [-]
From folder(s) - [-]
From item(s)
- [-]
- [-]
Unload after the request has been created.
- [-]
-
-
Provide a mechanism to resolve variable by name. Resolution should respect hierarchy: Global
<Collection
<Environment
<Json
<Data
<Local
. For example, if a given variable is defined inGlobal
andLocal
,Local
value should be used.-
Resolution should unfold variables until no matches are found. globalBaseUrl={{globalScheme}}://{{globalHost}}{{globalBasePath}}
thus in order to get value forglobalBaseUrl
, the value forglobalScheme
,globalHost
andglobalBasePath
should also be resolved. -
Prevent circular reference when unfolding variables
-
-
Add tests -
Check hierarchy resolution -
Check variable unfolding -
Check circular reference prevention, e.g.: var1="{{var2}}"
andvar2={{var1}}
inhttp://foo?q={{var1}}
-
Check indirect variable reference, e.g.: var1="var2"
andvar2={{var1}}
inhttp://foo?q={{{{var1}}}}
-
-
-
Introduce a new environmental variable _POSTMAN_COLLECTION_VARIABLES_GENERATION
. Instruct the request generator how to deal with undefined variables. There are three possible behaviors, represented by an enum:- Enum value
-
NONE
: Do not remove text of the unknown variable. Keep it as it is. -
DYNAMIC
: Replace only dynamic variables, other unknown variables will not be replaced. -
ALL
: Replace any unknown variable with a text value.
-
- Default to:
DYNAMIC
(in order to mimic postman runner behavior) - A unknown variable may fall into one of two categories:
-
Dynamic variable
: Any variable prefixed with$
. For these variables, a sample value can be formatted based on the list of postman dynamic variables. For instance$guid
can return611c2e81-2ccb-42d8-9ddc-2d0bfa65c1b4
instead of a generic fixed text. -
Any other unknown variables
: Since there is no hint about their expected type or format, we can set a fixed text such as:unknown-value
or a formatted text such as:unset-var-<varname>
. - The scanner may produce a warning log when variables for all unknown variables. This is because unknown variables can be part of any part of the request, and could lead to producing invalid content for the request generation.
-
-
Update worker-entry
to accept new environmental variable-
Add validation to accept only supported values
-
-
Update runner options -
Update postman reader to check _POSTMAN_COLLECTION_VARIABLES_GENERATION
and generate values for:-
Dynamic variables (on DYNAMIC
orALL
) -
Any other unknown variables (only when ALL
)
-
- In the scanner, log a list of the auto generated variables:
-
Collect name of the unknown variables while generating requests -
After generating request log the unknown variables .
-
-
Add test -
Add unit test with and without variable set. -
Add test to check generated values for dynamic variables
-
-
Add documentation for _POSTMAN_COLLECTION_VARIABLES_GENERATION
in API Fuzzing and DAST API-
Explain when it is expected to be used. -
Point out that generated value may not fit the expected value, and suggest providing environmental files.
-
- Enum value
-
Remove feature flag
Edited by Herber Madrigal