Package: secml
SecML: Secure and Explainable Machine Learning in PythonSecML is an open-source Python library for thesecurity evaluationof
Machine Learning algorithms.
It is equipped withevasionandpoisoningadversarial machine learning attacks,
and it canwrap models and attacksfrom other different frameworks.Table of ContentsGetting StartedUsageTutorialsContributingHow to cite SecMLContactsAcknowledgementsCopyrightGetting StartedSecML can run with Python >= 3.6 with no additional configuration steps
required, as all its dependencies are available as wheel packages for
the principal macOS versions, Linux distributions and Windows.InstallationInstall the latest version ofsetuptools:pipinstall-UsetuptoolsInstall from official PyPI repository:pipinstallsecmlIn all cases, the setup process will try to install the correct dependencies.
In case something goes wrong during the install process, try to install
the dependenciesfirstby calling:pipinstall-rrequirements.txtExtra ComponentsSecML comes with a set of extras components that can be installed if desired.
To specify the extra components to install, add the section[extras]while
callingpip install.extraswill be a comma-separated list of components
you want to install. Example:pipinstallsecml[extra1,extra2]The following extra components are available:pytorch: Neural Networks (NNs) throughPyTorchdeep learning platform.Installs:torch >= 1.4,torchvision >= 0.5Windows only: the url to installation archives should be manually provided aspip install secml[pytorch] -f https://download.pytorch.org/whl/torch_stable.html.foolbox: Wrapper ofFoolbox,
a Python toolbox to create adversarial examples that fool neural networks.Installs:foolbox >= 3.3.0,eagerpy >= 0.29.0,torch >= 1.4,torchvision >= 0.5cleverhans: Wrapper ofCleverHans,
a Python library to benchmark vulnerability of machine learning systems to adversarial examples.Installs:tensorflow >= 1.14.*, < 2,cleverhans < 3.1Warning: not available forpython >= 3.8tf-gpu: Shortcut for installingTensorFlowpackage with GPU support (Linux and Windows only).Installs:tensorflow-gpu >= 1.14.*, < 2Warning: not available forpython >= 3.8Advanced featuresTo support additional advanced features (like the usage of GPUs) more packages can be necessary
depending on the Operating System used:Linux (Ubuntu 16.04 or later or equivalent distribution)python3-tkfor running MatplotLib Tk-based backends;NVIDIA® CUDA® Toolkitfor GPU support.macOS (10.12 Sierra or later)Nothing to note.Windows (7 or later)Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019.NVIDIA® CUDA® Toolkitfor GPU support.UsageHere we show some of the key features of the SecML library.Wide range of supported ML algorithms.All supervised learning algorithms
supported byscikit-learnare available:# Wrapping a scikit-learn classifierfromsklearn.svmimportSVCfromsecml.ml.classifiersimportCClassifierSkLearnmodel=SVC()secml_model=CClassifierSkLearn(model)Also, SecML supports Neural Networks (NNs) throughPyTorchdeep learning platform:# Wrapping a Pytorch networkfromtorchvision.modelsimportresnet18fromsecml.ml.classifiersimportCClassifierPyTorchmodel=resnet18(pretrained=True)secml_model=CClassifierPyTorch(model,input_shape=(3,224,224))Management of datasets.SecML can bundle together samples and labels together in a single object:fromsecml.arrayimportCArrayfromsecml.dataimportCDatasetx=CArray.randn((200,10))y=CArray.zeros(200)dataset=CDataset(x,y)Also, you can load famous datasets as well:fromsecml.data.loaderimportCDataLoaderMNISTdigits=(1,5,9)# load subset of digitsloader=CDataLoaderMNIST()num_samples=200train_set=loader.load('training',digits=digits)test_set=loader.load('testing',digits=digits,num_samples=num_samples)Built-in attack algorithms.Evasion and poisoning attacks based on a
custom-developed fast solver. In addition, we provide connectors to other
third-party Adversarial Machine Learning libraries.fromsecml.adv.attacksimportCAttackEvasionPGDdistance='l2'# type of perturbation 'l1' or 'l2'dmax=2.5# maximum perturbationlb,ub=0.,1.# bounds of the attack space. None for unboundedy_target=None# None if untargeted, specify target label otherwise# Should be chosen depending on the optimization problemsolver_params={'eta':0.5,# step size of the attack'max_iter':100,# number of gradient descent steps}attack=CAttackEvasionPGD(classifier=secml_model,distance=distance,dmax=dmax,solver_params=solver_params,y_target=y_target)adv_pred,scores,adv_ds,f_obj=attack.run(x,y)A more detailed example covering evasion and poisoning attacks built-in in SecML can be found inthisnotebook.Wrapper of other adversarial frameworks.Attacks can also be instantiated using other framework as well.
In particular, SecML can utilizes algorithms fromfoolboxandcleverhans.fromsecml.adv.attacksimportCFoolboxPGDL2y_target=Nonesteps=100epsilon=1.0# maximum perturbationattack=CFoolboxPGDL2(classifier=secml_model,y_target=y_target,epsilons=epsilon,steps=steps)adv_pred,scores,adv_ds,f_obj=attack.run(x,y)A more detailed example covering attacks wrapped from other libraries can be found inthisnotebook.Dense/Sparse data support.We provide full, transparent support for both
dense (throughnumpylibrary) and sparse data (throughscipylibrary)
in a single data structure.fromsecml.arrayimportCArrayx=CArray.zeros((4,4))x[0,2]=1print(x)""">> CArray([[0. 0. 1. 0.][0. 0. 0. 0.][0. 0. 0. 0.][0. 0. 0. 0.]])"""x=x.tosparse()print(x)""">>  CArray((0, 2)  1.0)"""A more detailed example covering the usage of sparse data with an application in Android Malware Classification can be found inthisnotebook.Visualize your results.We provide a visualization and plotting framework,
based on the widely-known librarymatplotlib.fromsecml.figureimportCFigurefromsecml.optim.constraintsimportCConstraintL2fig=CFigure(width=5,height=5,markersize=12)fig.subplot(1,2,1)# Plot the attack objective functionfig.sp.plot_fun(attack.objective_function,plot_levels=False,n_grid_points=200)# Plot the decision boundaries of the classifierfig.sp.plot_decision_regions(secml_model,plot_background=False,n_grid_points=200)# Plot the optimization sequencefig.sp.plot_path(attack.x_seq)# Plot a constraintfig.sp.plot_constraint(constraint)fig.title("SecML example")fig.show()Explain your results.Explainable ML methods to interpret model decisions
via influential features and prototypes.fromsrc.secml.explanationimportCExplainerIntegratedGradients# Compute explanations (attributions) w.r.t. each classattributions=CArray.empty(shape=(dataset.num_classes,x.size))forcindataset.classes:attributions_c=CExplainerIntegratedGradients(clf).explain(x,y=c)attributions[c,:]=attributions_c# Visualize the explanationsfig=CFigure()# Threshold to plot positive and negative relevance values symmetricallythreshold=max(abs(attributions.min()),abs(attributions.max()))# Plot explanationsforcindataset.classes:fig.sp.imshow(attributions[c,:].reshape((dataset.header.img_h,dataset.header.img_w)),cmap='seismic',vmin=-1*threshold,vmax=threshold)fig.sp.yticks([])fig.sp.xticks([])fig.show()A more detailed example covering explainability techniques can be found inthisnotebook.Model Zoo.Use our pre-trained models to save time and easily replicate
scientific results.fromsecml.model_zooimportload_modelclf=load_model('mnist159-cnn')TutorialsWe provide tutorials that cover more advanced usages of SecML, and they can be found inside thetutorialsfolder.ContributingThe contributing and developer's guide is available at:https://secml.readthedocs.io/en/latest/developers/How to cite SecMLIf you use SecML in a scientific publication, please cite the following paper:secml: A Python Library for Secure and Explainable Machine Learning, Meliset al., arXiv preprint arXiv:1912.10013 (2019).@article{melis2019secml,title={secml: A Python Library for Secure and Explainable Machine Learning},author={Melis, Marco and Demontis, Ambra and Pintor, Maura and Sotgiu, Angelo and Biggio, Battista},journal={arXiv preprint arXiv:1912.10013},year={2019}}ContactsThe best way for reaching us is by opening issues. However, if you wish to contact us, you can drop an email to:maura.pintor@unica.itluca.demetrio93@unica.itAcknowledgementsSecML has been partially developed with the support of European Union’sALOHA projectHorizon 2020 Research and
Innovation programme, grant agreement No. 780788.CopyrightSecML has been developed byPRALab - Pattern Recognition and Applications labandPluribus One s.r.l.underApache License 2.0. All rights reserved.