Adaptative Perturbation Pattern Method
======================================
A2PM is a gray-box method for the generation of realistic adversarial examples.
It benefits from a modular architecture to assign an independent sequence of
adaptative perturbation patterns to each class, which analyze specific feature
subsets to create valid and coherent data perturbations.
This method was developed to address the diverse constraints of domains with
tabular data, such as cybersecurity. It can be advantageous for adversarial
attacks against machine learning classifiers, as well as for adversarial
training strategies. This Python 3 implementation provides out-of-the-box
compatibility with the Scikit-Learn library.
If you use A2PM, please cite the primary research article: `https://doi.org/10.3390/fi14040108 <https://doi.org/10.3390/fi14040108>`_
Check out the official documentation: `https://a2pm.readthedocs.io/en/latest <https://a2pm.readthedocs.io/en/latest/>`_
Explore the public source code repository: `https://github.com/vitorinojoao/a2pm <https://github.com/vitorinojoao/a2pm>`_
.. figure:: https://raw.githubusercontent.com/vitorinojoao/a2pm/main/images/a2pm.png
:alt: A2PMFigure
How To Install
--------------
The package and its dependencies can be installed using the pip package manager:
::
pip install a2pm
Alternatively, the repository can be downloaded and the package installed from the local directory:
::
pip install .
How To Setup
------------
The package can be accessed through the following imports:
.. code:: python
from a2pm import A2PMethod
from a2pm.callbacks import BaseCallback, MetricCallback, TimeCallback
from a2pm.patterns import BasePattern, CombinationPattern, IntervalPattern
from a2pm.wrappers import BaseWrapper, KerasWrapper, SklearnWrapper, TorchWrapper
A2PM can be created with a simple base configuration of Interval and/or Combination
pattern sequences, which have several possible parameters:
.. code:: python
pattern = (
# First pattern to be applied: Interval
{
"type": "interval",
"features": list(range(0, 20)),
"integer_features": list(range(10, 20)),
"ratio": 0.1,
"max_ratio": 0.3,
"missing_value": 0.0,
"probability": 0.6,
},
# Second pattern to be applied: Combination
{
"type": "combination",
"features": list(range(20, 40)),
"locked_features": list(range(30, 40)),
"probability": 0.4,
},
)
method = A2PMethod(pattern)
To support domains with complex constraints, the method is highly configurable:
.. code:: python
# General pattern sequence that will be applied to new data classes
pattern = (
# An instantiated pattern
MyCustomPattern(1, 2),
# A pattern configuration
{
"type": MyCustomPattern,
"param_name_1": 3,
"param_name_2": 4,
},
)
# Pre-assigned mapping of data classes to pattern sequences
preassigned_patterns = {
# None to disable the perturbation of this class
"class_label_1": None,
# Specific pattern sequence that will be applied to this class
"class_label_2": (
MyCustomPattern(5, 6),
{
"type": MyCustomPattern,
"param_name_1": 7,
"param_name_2": 8,
},
),
}
method = A2PMethod(pattern, preassigned_patterns)
How To Use
----------
A2PM can be utilized through the 'fit', 'partial_fit', 'transform' and 'generate'
methods, as well as their respective shortcuts:
.. code:: python
# Adapts to new data, and then creates adversarial examples
X_adversarial = method.fit_transform(X, y)
# Encapsulates a Tensorflow/Keras classification model
classifier = KerasWrapper(my_model, my_custom_class_labels)
# Adapts to new data, and then performs an untargeted attack against a classifier
X_adversarial = method.fit_generate(classifier, X, y)
# Adapts to new data, and then performs a targeted attack against a classifier
X_adversarial = method.fit_generate(classifier, X, y, y_target)
To analyze specific aspects of the method, callback functions can be called before
the attack starts (iteration 0) and after each attack iteration (iteration 1, 2, ...):
.. code:: python
X_adversarial = method.fit_generate(
classifier,
X,
y,
y_target,
# Additional configuration
iterations=10,
patience=2,
callback=[
# Time consumption
TimeCallback(verbose=2),
# Evaluation metrics
MetricCallback(classifier, y, my_custom_scorers, verbose=2),
# An instantiated callback
MyCustomCallback(),
# A simple callback function
MyCustomFunction,
],
)